Setup Guide, Week 1: Connect your data
Last updated: November 4, 2026
In your first week, you connect the tools Span reads from: source control, your people data and your issue tracker, plus the optional sources that round out the picture. This guide is for the admin setting up Span for your organization.
Why it matters
Every report, team view and permission in Span depends on the data you connect now. Getting the essentials right in week 1 means the numbers your teams see later are complete and trustworthy.
For admins: a clear order of what to connect, and what each source unlocks.
For engineering leaders: a chance to agree what Span is for before anyone logs in.
How it works
You connect each tool in Settings → Integrations. Span then backfills history so you can compare before and after. Source control, people data and an issue tracker are required. The rest are recommended or optional, so add them when they fit.
Source | What it unlocks |
|---|---|
Source control | PR cycle time, review and throughput metrics |
People and teams | Team views, manager permissions and Git identity matching |
Issue tracker | Issue cycle time, sprint tracking and allocation |
Incidents | Mean time to recover and change failure rate |
Slack and Src | Ask Src questions in Slack, and get digests and alerts there |
Calendar and out of office | Focus time, meeting load, and fair metrics during time away |
Agent traces | How AI coding agents are used, and what AI costs per merged PR |
Setup
You need the Owner or Admin role in Span, or an Integrations Admin. You also need admin access to each tool you connect.
1. Agree on the purpose
Why: Engineers trust and use Span when they hear up front that it's for improving how work flows, not for ranking people.
How: Decide as a leadership team what Span is for and how the data will be used. Share it with engineers before anyone logs in.
Docs: Span products and use cases
2. Connect source control
Why: This is the core of Span. PR cycle time, review speed and throughput all come from it.
How: Go to Settings → Integrations and connect GitHub (including Enterprise), GitLab (Cloud or self-managed) or Azure DevOps Repos. Bitbucket Cloud is also supported: Span turns it on for your organization on request. One provider is enough to start.
Docs: Ways to connect GitHub · GitHub Enterprise Cloud with data residency · GitLab integration
3. Load your people and teams
Why: Every team view, manager permission and per-person metric depends on your roster. This is what puts the numbers in the right place.
How: Choose one source. An HRIS integration is best (for example Workday, BambooHR, HiBob, Rippling or ADP). A directory works too (Okta, Google Workspace, Microsoft Entra ID, or a Directory Sync JSON file). A CSV upload is the fastest start. When it worked, People Management lists everyone who writes code with a manager and a team.
Docs: People data & roster management · Workday HRIS · Okta as an HRIS · Using Directory Sync · CSV import
4. Connect your issue tracker
Why: It adds the planning side of the picture: issue cycle time, sprint predictability and where engineering effort goes.
How: Connect Jira (Cloud or Data Center), Linear, GitHub Issues or Azure DevOps Boards.
Docs: Jira integration · Linear integration
5. Connect your incident tool
Why: It shows how safely you ship, through mean time to recover and change failure rate.
How: Connect incident.io or Rootly. If you use PagerDuty or Opsgenie, send incidents to Span through the DORA API.
Docs: incident.io · Rootly · Set up DORA metrics
6. Connect Slack and ask Src a question
Why: Slack is how Span delivers digests, alerts, playbooks and surveys. It also lets people ask Src, the assistant inside Span, questions where they already work.
How: Connect Slack, then try asking Src "Where does our team's work wait longest?"
Docs: Src Slack setup guide · Using Src
7. Connect calendar and out of office
Why: It shows how much meetings cut into focus time, and keeps metrics fair when people are out.
How: Connect Google Calendar or Microsoft Outlook (Microsoft 365). Then, in Settings → Org Calendar, choose your Out of Office Days Source: your calendar or your HRIS.
Docs: Connecting an OOO data source · Focus Time
8. Optional: set up SSO and SCIM
Why: People sign in with their company identity, and access is granted and removed automatically as people join and leave.
How: Set up SSO with Okta, Entra ID or Google Workspace. Ask Span to turn on SCIM if you want automatic access changes.
Docs: Setting up SSO · SCIM provisioning · Network access requirements
9. Optional: start agent traces
Why: Traces show how AI coding agents are really used, where people had to step in, and what AI costs per merged PR. Skip this if measuring AI effectiveness isn't a goal yet.
How: Traces use auspex, a small agent on each engineer's machine that captures Claude Code, Cursor, Codex and Copilot sessions, with redaction on the device. Have Security review it, pilot with two engineers for a couple of days, then roll out with your MDM or self-install.
Docs: Understanding agent traces · Security overview · Trace screening · Jamf (macOS) · Intune (macOS) · Intune (Windows) · Self-install on macOS · Self-install on Windows · Self-install on Linux · Verify auspex is sending traces
Things to know
History: by default, a new organization backfills 6 months of history, so trends are there once the first sync finishes. The first sync can take a few hours.
Sync timing: most integrations sync about every 2 hours. HR system changes arrive when the source changes, then wait on Settings → Directory Sync for your review. Span can turn on auto-apply for your organization on request.
Tokens expire: if you connect with a token (GitLab or Azure DevOps), use the longest expiry your policy allows and name someone to renew it. Span checks each connection every 6 hours and pauses it after two failed checks in a row.
Email is the match key: use the same work email people use for Git and their AI tools. Span matches people across every tool by email.
CSV uploads replace everything: people missing from the file are terminated, with their history kept. Download a backup of your directory before every upload.
SCIM doesn't build your roster: it grants and removes access for people already in Span. It doesn't create people or set teams and managers, so you still need step 3.
You're ready for week 2 when
Source control, your people data and your issue tracker are connected and syncing.
Everyone who writes code is in Span with a manager and a team.
Slack is connected and you've asked Src your first question.
You've decided which optional sources to add.
Engineers have heard from a leader what Span is for.
Related articles
Need help?
Contact your Span account team or reach out to support@span.app.