Set up Span in your first two weeks: a guide for admins
Last updated: November 2, 2026
A step-by-step checklist for your organization's Span admins for the first two weeks after the contract starts. Each step links to the article with the detail.
Why it matters
A few setup choices decide whether managers trust the first numbers they see. By day 14 you should have:
Data flowing from your Git host, issue tracker and AI tools, with no connection showing Reconnect required.
The right people with the right access: a roster with managers and teams, Git accounts linked, and permission groups set.
First team reviews done, with each team's targets live and digests going to managers or Slack.
Before you start
Span admin: someone in the Owners or Admins group. Span sets up both groups and adds the people you name. Owners can also manage permission groups; Admins can't.
Git host and issue tracker admin: to install the GitHub App or create the tokens Span needs. You can delegate integrations through the built-in Integration Admins group.
Identity provider or HRIS owner: for SSO, SCIM and the roster source.
IT or MDM owner (optional): only if you'll collect agent traces with auspex.
Week 1: connect and configure
Sign-in, SSO and SCIM. Set up SSO under Settings → Single Sign-On so people sign in through your identity provider, and ask Span to turn on SCIM Setup if you want access granted and revoked automatically. SCIM doesn't create people or change teams. See Setting up SSO with Span and Setting Up SCIM Provisioning for Span.
Connect your Git host. In Settings → Integrations, connect GitHub, GitHub Enterprise, GitLab, Azure DevOps, or Bitbucket Cloud (Span turns it on for your organization on request). When you install the GitHub App, choose which repositories it can read. See Ways to connect GitHub to Span or GitLab Integration.
Connect your issue tracker. Jira, Linear, GitHub Issues or Azure DevOps Boards power issue lifecycle, PR linking and allocation. See Jira Integration or Linear <> Span Integration.
Connect a calendar (optional). Google Calendar or Microsoft Calendar adds focus time, meeting load and out-of-office days. Span reads event times, attendees, titles and descriptions.
Load people and teams. Pick one roster source. An HR system (connected in Settings → Integrations, then set up by Span as your roster source) or the Span Sync API keeps people, managers and teams current through Directory Sync, where you review each change before it applies. A CSV upload (Settings → People Management → Add member → Sync from CSV) replaces the whole directory each time. SSO and SCIM don't build the roster. See Using Directory Sync for Roster Management and CSV Import of People + Team Data.
Set contributor status and link Git accounts. In People Management, mark people who write code as Contributor and add their GitHub Usernames or GitLab Usernames. Unlinked PRs don't count toward anyone. See What determines contributor status in Span user profiles? and Linking people to their GitHub and GitLab accounts.
Review permission groups. In Settings → Permission Groups, check the built-in groups: Team Members (everyone), Managers (anyone with direct reports), Team Leads, Owners and Admins, plus Integration Admins, Survey Admins and Finance Admins. Add named people where needed. See Roles & Permissions in Span.
Tune metrics settings. In Settings → Metrics, add Ignore Repositories, Ignore Branches and Ignore Git Usernames for bots, and check Cycle & Response Times: Weekends. In Settings → Org Calendar, set the Time Zone and the Out of Office Days Source (Calendar Integration or HRIS Integration). See Metrics Settings and Connecting an OOO Data Source in Span.
Connect AI tools. Add the ones you use: Cursor, GitHub Copilot (a switch on your GitHub connection), Claude Code, ChatGPT & Codex Workspace for ChatGPT Enterprise, and OpenAI Platform for OpenAI API usage.
Roll out agent traces (optional). Your IT team deploys auspex through MDM with the org token from Settings → Traces → Trace collection → View token. Traces supply AI code ratio and the Comparison report. Whether to tell engineers is your decision; Span recommends telling them. See Understanding Agent Traces in Span (auspex), the IT admin guide for your MDM (for example Jamf Pro or Microsoft Intune (Windows)), and Fleet diagnostics.
Week 2: verify and roll out
Verify the data. In Settings → Integrations, every connection should be under Connected with no Reconnect required badge. In People Management, open the Data Quality Issues drawer and add or ignore each unmatched contributor. Spot-check a few recent PRs in Catalog → Pull Requests against your Git host. See Troubleshooting integration connection status.
Invite managers and engineers. Give people a Span login by setting their Access Type to Account, which sends the invite, or let SCIM grant it. See How do I add a new user to Span?
Set up Targets for each team. Open a team under Organization → Teams and use Set targets, or go to Targets → Manage. See Targets: set team goals and get notified when work slips, and PR Link Rate Report.
Turn on digests. Managers use Settings → Personal → Notifications for email digests; each team picks a channel under Settings → Team Settings → Slack Digest. Slack must be connected first. See Summary Notifications.
Try Src and a Playbook. Ask Src a question about your data, then save a recurring report as a Playbook from Playbooks in the left navigation. Creating Playbooks needs the Manage Playbooks permission, which Owners and Admins have by default. See Using Src to understand your engineering metrics and Using Src Playbooks.
Run a first team review. With one manager, walk through their team page (Overview, Metrics, Targets). Fix anything that looks wrong before rolling out to more teams.
Things to know
History: by default, Span loads history from 6 months before your organization was created, so trends are there on day one.
Sync timing: connectors sync about every 2 hours. A Jira change shows within about 5 hours. HR system changes arrive when the source changes and wait for your review unless Span turns on auto-apply.
Before go-live: while Span checks your data, Settings → Integrations shows Your integrations are syncing... and most of the app stays hidden, including the Single Sign-On, SCIM Setup, Directory Sync, Metrics, Org Calendar, Team Settings and Notifications settings pages. Span opens it once the data looks right; finish those steps then.
Broken connections: Span checks each connection every 6 hours and pauses it after two failed checks in a row.
Common setup mistakes: missing Git usernames (PRs don't count toward anyone), bot accounts left in metrics, uploading a partial CSV (people missing from the file are terminated), and expecting SCIM to create people.
Agent traces need Span to turn on trace processing. Ask your Span account team when you start the rollout. See How long before a trace shows up in Span?
Worked example: Span creates your organization on Monday, November 2, so history starts May 2. Day 1: you connect GitHub at 10:00 and Jira at 11:00, and Span starts syncing both on its next 2-hour cycle. Day 2: your HR system's first load takes about 10 minutes. Days 3 to 5: Git usernames, permission groups and AI tools. Once Span opens the app, you approve the first directory sync and finish SSO and metrics settings. Day 8: the Data Quality Issues drawer shows 6 unmatched contributors, 4 people and 2 bots; you add the people and ignore the bots. Days 9 to 14: invites go out, each team sets targets, and the first team review happens.
Related articles
How to create an Integrations Admin in Span
How teams and team membership work in Span
Need help?
Contact your Span account team or reach out to support@span.app.