Setup Guide, Week 2: Configure your org

Last updated: November 4, 2026

In week 2, you make Span match how your organization works: who's counted, how teams are set up, who sees what, and how metrics are calculated. This guide is for the admin, and the engineering leader who decides who sees what.

Why it matters

Small fixes here make every number your teams see more trustworthy. Unmatched Git authors, bots counted as people, or teams that don't match reality can skew metrics before anyone reads them.

For admins: a checklist of settings to confirm before you invite people.
For engineering leaders: control over who sees what, set and tested before rollout.

How it works

Most of this week happens in Settings and People Management. Changes to teams, permissions and metrics settings apply to reports after the next sync, so you can fix things now before anyone else logs in.

Setup

You need the Owner role to change permission groups. Admins can do the other steps.

1. Match Git identities

Why: PRs from an author Span can't match don't count toward anyone, so team numbers come out too low.

How: Open the Data Quality Issues drawer on People Management and add or ignore each unmatched author. GitHub and GitLab need a username on each person. Azure DevOps, Jira and Bitbucket match by email. When it worked, the drawer is empty.

Docs: Linking people to Git accounts · Troubleshooting GitHub data quality

2. Set contributor status and remove bots

Why: Team averages should reflect the people who write code day to day, and bot accounts inflate PR counts.

How: Mark contractors, managers who rarely commit, and occasional coders as Observer or Non-contributor. Add bot accounts to Ignore Git Usernames in Settings → Metrics.

Docs: Contributor status · Offboarding and terminated people

3. Check your teams

Why: Metrics roll up by team, so teams that don't match how work really happens put numbers in the wrong place.

How: If teams come from your HRIS or directory, change them there. Otherwise, edit them in Settings → Team Management. A person can belong to more than one team.

Docs: How teams work · Creating a team · How Span attributes metrics to teams

4. Set roles and permissions

Why: Permission groups control who sees what in Span, including team data, individual data and agent traces. Setting them before you invite anyone means no one sees more than you intended.

How: Go to Settings → Permission Groups and review the built-in groups, such as Managers and Team Leads. Adjust what each group can see, and add groups for anyone who needs different access. Then check a sample engineer, manager and leader on the Permissions tab of their profile.

Docs: Roles & permissions · Agent Trace permissions

5. Set up deployments

Why: Deployment frequency and lead time to production, two of the four DORA metrics, need to know when you ship.

How: Send each deploy to Span's DORA API from GitHub Actions, AWS CodePipeline or any other CI tool.

Docs: Set up DORA metrics · Send deployments from GitHub Actions or AWS CodePipeline · DORA API

6. Connect your AI coding tools

Why: For AI adoption and AI spend by tool, team and person, shown next to your delivery metrics.

How: Connect Cursor, GitHub Copilot (a switch on your GitHub connection), Claude Code, ChatGPT and Codex, or the OpenAI Platform.

Docs: Supported AI coding tools · Cursor · GitHub Copilot · Choosing the right Claude Code integration · OpenAI Platform · ChatGPT & Codex

7. Confirm sprint settings

Why: For planning accuracy and spotting work that rolls over from sprint to sprint. Skip this if your teams don't run sprints.

How: Check that Span reads your sprints correctly in the Sprint Tracking report.

Docs: Sprint Tracking Report · Issue Completion Rate Report

8. Tune metrics settings

Why: Keeps cycle times honest, so a PR opened Friday and merged Monday doesn't look slow because of the weekend.

How: In Settings → Metrics, check Cycle & Response Times: Weekends and add any repositories or branches to ignore. In Settings → Org Calendar, set your organization's Time Zone. Changes show after the next metrics sync.

Docs: Metrics Settings · Weekend exclusion · PR Cycle Time Threshold Filter

9. Tune work categories

Why: For seeing where effort goes, such as new features versus maintenance, in the terms your leadership already uses.

How: Rename and merge Workstreams to match how your organization talks about its work. On Jira, you can also add Labeled Investment rules for the categories leadership reports on.

Docs: Allocation overview · Refining your Workstreams · Setting up Labeled Investment

Things to know

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.
Access adds up: a person gets access from every group they belong to. If a manager can still see individuals, look for another group that grants People permissions.
Timing: team edits take about 30 minutes to show in reports.
Contributor status is manual for contractors: Span doesn't use employment type from your HRIS, so mark contractors yourself.
Data, classification or process: when a number surprises you, ask which kind of problem it is. Data means unmatched authors, missing repos or bots counted as people. Classification means work landed in the wrong category. Process means the number is right. Fix the first two now. The third is your improvement opportunity for week 3.
Read trends, not single weeks: "/ week" metrics are most useful across several weeks.

You're ready for week 3 when

The Data Quality Issues drawer is empty, and contractors and occasional coders are marked.
Teams match how work really happens.
Permissions are set and tested with a sample engineer, manager and leader.
Deployments, AI tools and sprint settings are configured where they apply.
Metrics settings and work categories reflect how your organization works.

Need help?

Contact your Span account team or reach out to support@span.app.