# Setting it up

Setting up Engineering Delivery means connecting the tools your teams use, then telling the app how your teams work: what counts as a deploy, which tracker statuses mean what, and who belongs to which team. This page walks through each step, and then answers the most common question after setup: why does a tile say it is not connected or not measured?

> **Note:** Setup, Settings and Access sit in the Admin place on the app's rail. Only environment admins see them. If you are not an admin, share this page with someone who is.

## How do I connect my tools?

You connect tools on the **Setup** screen, and the app starts pulling their data straight away and then every three hours.

Each tool in Setup has a short line saying what the app reads from it, and a **Connect** button that opens a small form. The tools it reads:

| Tool | What the app reads |
| --- | --- |
| GitHub | Pull requests, reviews, commits and Actions runs |
| GitLab | Merge requests, approvals, merge commits and deployments |
| Bitbucket | Pull requests, approvals, change sizes and commits |
| Jira | Issues, how they move and the projects they belong to |
| Linear | Issues and how they move |
| PagerDuty | Incidents: when each opened and was resolved, its service, team and priority, never who responded |
| Anthropic and OpenAI | What your organisation spends on Claude or OpenAI |
| Review agents | Whether Solidafy's review agents passed each pull request |

The forms link straight to where each token is made, for example GitHub's token settings or your Atlassian API tokens, and say which permissions to tick. For GitHub that is **repo** and **read:org**, nothing else.

For Claude Code, the Anthropic connection gives daily totals. For tools, sessions and permission decisions, Claude Code sends its own telemetry. [Connecting Claude Code](/docs/engineering-delivery/claude-code-setup) explains the three ways to connect it.

> **Tip:** If Setup says "Someone who can manage Data Sources needs to connect" a tool, you can see the app but not add data sources. Ask whoever manages data sources in your organisation.

### What happens after I connect?

Setup shows the data moving through five steps: **Pull** brings in each tool's data, **Clean** keeps one tidy row per item, **Shape** puts every tool into one shared shape, **Work out** works out journeys, deploys, fixes and AI spend, and **App tables** holds the team level tables the app reads. When the button says **Set up** or **Apply changes**, it lists what it will do before you press it.

### Which tool do I need first?

Start with your code host. Deploys, change lead time, review times and change size all come from it. Add your tracker next for the Flow measures, an incident source for precise recovery time and rework rate, and AI billing for the AI page.

## How do I tell the app how my teams work?

You decide how the app counts in **Settings**. Each section has a short description, a line saying where in the app the change shows, and a **How this works** button that explains what the section decides, what happens if you leave it alone, and an example from your own numbers.

Some sections apply at once. Others change how the data is worked out, so they say "Applies after the next rebuild": the new numbers appear once the app has recomputed them.

### What counts as a deploy

This is the most important setting, because deployment frequency, change lead time, change fail rate and recovery time are all counted from it. The choices are:

- **"Detected for each repository"**: the app works out the deploy signal per repository.
- **"A production deployment"**: a deployment to production that your pipeline reports.
- **"A merge to the main branch"**: for teams where a merge ships automatically.
- **"A tagged release"**: for teams that release by tagging a version.

Pick the one that matches the moment users actually get a change. You can also leave whole repositories out of deploys, under What to leave out.

### Statuses and stages

Your tracker has its own status names. Here you map each one to a stage: **Backlog**, **In progress**, **Review**, **Testing** or **Done**. Time in each stage, stuck work and ticket cycle time all follow this mapping, so a status left unmapped is time the app cannot place.

### People and teams

**People** lists each person once, with every account they use in your tools: two GitHub accounts, a Linear and a Jira account, a Claude Code account, any mix. You choose each person's team as you join their accounts, and every account of theirs counts for that team.

**Teams** picks the people in each team from People, and the repositories each team owns. A person's changes, reviews, deploys and failures count for their team in any repository they work in. A repository a team owns only places a deploy that shipped no change. Both sections are "used only to group, never shown": they decide which team work counts for, and the measures never name anyone.

**Smallest team shown on its own**, also under Teams, is the fewest engineers (people with a code host account) a team needs for its numbers to show on their own, 3 unless you change it, from 1 to 10. A smaller team counts only in All teams, with the people in no team. It decides which teams the team filter offers and which teams every team table lists. While Names on items or Claude Code by person is on, people are shown anyway, so every team shows its own numbers.

**Names on items**, off by default, shows who each item is by when someone opens it from a figure: a change's author and reviewers and a ticket's assignee, by the name their tool gives them. Measures, charts, Scout, alerts and the standup and retro screens stay team level either way, and no one is ever ranked.

### Incident source

Where your incidents are recorded: **Jira**, **Linear** or **PagerDuty**, plus the project or label that marks an incident and the priorities that count. With Jira or Linear you pick the project and the label from the lists your tracker gives, so with Linear the project is a Linear project. With Linear you can also pick a **Linear view**: its issues are your incidents, along with any project and label you chose. Recovery time is read from these incidents once they arrive, and from releases that needed a fix until then. Deployment rework rate needs an incident source and is not measured without one. Opsgenie is being retired by Atlassian, so choose Jira (Jira Service Management), Linear or PagerDuty instead.

### Review policy

Which review counts, per repository. There are three policies:

- **"Agent or person (default)"** counts a person approving, or the review agents passing the commit that was merged.
- **"Green checks or a person"** counts every required check on the merged commit passing before the merge, or a person approving. With no check marked required, every check must pass. Checks are read from GitHub; elsewhere only a person counts.
- **"A person must approve"** counts only a person.

Under any of them, a repository can also tick **"A person's review comment counts as a review"**: someone other than the author leaving a review comment or asking for changes before the merge then counts, as an approval does. This is read from GitHub; GitLab and Bitbucket record only approvals, so there only an approval counts. Review coverage and merged without review follow this setting. See [Review coverage](/docs/engineering-delivery/review#review-coverage).

### What to leave out

By default, pull requests that Dependabot, Renovate or another bot opened, and Jira issues an app reported, are left out of every measure. Tick **"Count changes and tickets made by bots"** to include them. Deploys count whoever merged them either way.

You can also write your own rules, for example leaving out a repository, a branch or a ticket type. A rule leaves an item out when all its conditions hold. As the app puts it, "Rules are for automation and work that is not delivery, never to leave out a person." Guides in the app say how many changes your rules leave out in the period, so nothing disappears silently.

### The other sections

- **Sprints:** whether your teams work in sprints, how long one is (one to four weeks) and when the first started. With sprints the retro covers the sprint in progress; without, the last 14 days.
- **Focus, Goals and budgets, Working agreements and Alerts:** see [Overview, focus and working agreements](/docs/engineering-delivery/overview-and-focus) and [Goals, alerts and Scout](/docs/engineering-delivery/goals-alerts-and-scout).
- **Scout:** whether the weekly note and the retro nudge are sent, who writes them (the app's rules by default, or Scout in its own words), and whether people can use Ask Scout, which is off until you turn it on. See [Goals, alerts and Scout](/docs/engineering-delivery/goals-alerts-and-scout#scout).
- **AI subscriptions, Exchange rates, AI spend by team and AI payback assumptions:** seat based plans no billing source reports, their currency, how to split spend between teams, and the assumptions behind payback. See [AI](/docs/engineering-delivery/ai).
- **Retro notes:** lets teams write down keep, stop, start and shout outs beside the retro numbers. Notes are never signed.
- **Colours:** the app's accent colours, checked so text stays readable in both themes.
- **Who can open the app:** on the **Access** screen, the people and security groups who can open the app and the teams each sees. Environment admins always see every team.

### How do I uninstall the app?

At the foot of Settings, a **Danger zone** holds **Uninstall app**. It removes everything the app made in this environment, so you can set it up again from scratch. Before anything goes, it lists what will be removed: its operator (Scout) and schedules, its pipelines and their runs, its catalog tables, its access policies, its alerts, notes and saved items, its saved settings, and last its install. You confirm by typing the app's name.

If the app created data sources for you, you can tick **"Also remove the data sources this app created"**. Your own data sources are never removed. If an uninstall stops part way, Settings says where it stopped and the button reads **Finish uninstalling**.

## Why does a tile say it is not measured?

A tile that cannot be measured never shows a number. Instead it says what is missing, because the app never estimates. Here is what each message means and what to do.

### "Connect your code to see deploys, lead time and fixes. Nothing is estimated."

No code host is connected yet. Connect GitHub, GitLab or Bitbucket in Setup. Most of the Overview, Speed, Review and Quality pages come from it.

### "Connect ... to see ... No number is estimated."

The measure needs a kind of tool you have not connected, for example a tracker for work in progress. An admin sees a button on the tile that goes straight to the fix: **"Connect it in Setup"**, **"Choose the incident source"** or **"Add an AI subscription"**.

### "The app does not read ... yet, so this is not measured."

The data exists somewhere, but either the app does not read that kind of data yet, or the tool you connected does not report it (for example, a code host that does not link commits to changes). Connecting more of the same tool will not help, so the tile shows no button.

### Why is deployment rework rate not measured?

Rework rate counts deploys made while an incident was open, so it needs an incident source. Choose one under Incident source in Settings. Once chosen, the tile says that incidents arrive after the next pipeline run and rework rate is measured from then.

### Why do I see "Incidents are not read yet"?

The Incidents page reads incident counts, incidents by service and rework rate from your incident source. Until it is connected and read, recovery time on that page is measured from releases that needed a fix instead.

### Why is focus time never measured?

Focus time means working hours free of meetings, and only a calendar shows a meeting. The app does not read calendars yet, so it shows focus time as not measured rather than guessing.

### Why does AI payback say it needs my AI cost?

Payback weighs the time AI saves against what it costs, so it needs your AI spend. Connect Anthropic or OpenAI billing in Setup, or add your seat based plans under AI subscriptions in Settings. Payback also needs at least one AI-assisted change and at least one other change in the period, so it has something to compare.

### Why does the goals preset say "No baseline yet"?

The **"Suggest goals 10% better than now"** preset works from your own numbers, so it is offered once the app has measured them. It appears after the first data has been worked out.

### Why is a team missing?

A team with fewer engineers than **Smallest team shown on its own** (3 unless you change it, in Settings under Teams) is not shown on its own, on any page, so no one can be singled out. The team filter lists it, unavailable, with why, and the team tables on the Brief, Team health and AI name it underneath. While Names on items or Claude Code by person is on, people are shown by name anyway, so every team is shown on its own. Its work is still counted in All teams, with the people in no team. Check People and Teams in Settings if a larger team is missing: every person needs to belong to a team for their work to count for it.

## Why does a number look wrong?

Most surprising numbers come from one of four settings.

- **Deploys look too high or too low.** Check What counts as a deploy. A merge-based rule on a repository that really releases weekly will count far more deploys than users see.
- **Time in each stage or stuck work look odd.** Check Statuses and stages. A status mapped to the wrong stage, or not mapped at all, moves time to the wrong place.
- **A team's numbers look too small or too large.** Check People and Teams. Work by someone in no team, or from an account not joined to a person, counts for no team.
- **Change counts look inflated.** Check whether bots count, under What to leave out. Dependency update bots can open many small pull requests.

> **Tip:** Changes to these settings say "Applies after the next rebuild". Give the app a little time before judging the new numbers.

## Learn more

- [What is Engineering Delivery?](/docs/engineering-delivery/overview)
- [Overview, focus and working agreements](/docs/engineering-delivery/overview-and-focus)
- [Speed](/docs/engineering-delivery/speed)
- [Incidents](/docs/engineering-delivery/incidents)
- [Goals, alerts and Scout](/docs/engineering-delivery/goals-alerts-and-scout)