Connect GitHub

Connect GitHub to see what your teams ship in Engineering insights, and, if you choose, to sharpen the weekly effort estimate. Flowstate only reads from GitHub. It never changes your repositories.

For every field, disconnecting and sync history, see GitHub.

Before you start

• In GitHub: someone who can install GitHub Apps on your organisation — usually an organisation owner.
• In Flowstate: a Flowstate admin who can manage integrations.
• Your people are in Flowstate with their work email addresses, so their GitHub accounts can be matched to them. See People and teams.
• Engineering insights is switched on for your organisation. See Switching it on.
• Recommended: Linear or Azure DevOps connected, so pull requests can be tied to tickets and projects. See Connect your project tool.

What Flowstate reads

Flowstate reads details about your code, not the code itself:

• pull requests — title, author, branches, state, when they opened and merged, and lines added and removed;
• commits — author, time, message and which pull request they belong to;
• reviews on pull requests, to measure review times;
• contributor accounts, to match them to your people.

You choose all repositories or a selected list when you install the app. Only those are read.

1. Install the GitHub App

1. Go to Settings → Integrations and select Browse catalog.
2. Open GitHub.
3. Select Connect. GitHub opens.
4. In GitHub, choose the organisation and All repositories, or the repositories you want, and install the app. You come back to the Configure GitHub page.

Done when: the Connection step shows your Account, Repositories, Installed by and Installed.

Choose All repositories so the whole company's work is seen, not just some teams'.

When you connect, Flowstate imports the last 8 weeks of pull requests and commits. After that, changes arrive as they happen.

2. Map contributors

Flowstate matches most GitHub accounts to your people by email. Match the rest by hand.

1. Open the Map contributors step.
2. Select Open the mapping hub. User attribution opens.
3. Under Unattributed, select GitHub to show only GitHub accounts.
4. On each account's row, select Select employee... and pick the person.

Done when: the Map contributors step says "Every active contributor is mapped".

• GitHub usernames often aren't people's real names. Check the email shown under the username.
• An unmatched contributor's code doesn't shape effort and has no cost.
• Automated accounts that Flowstate recognises are left out of the count. Bots and utility accounts count towards pull request volume, but never towards cost, and are left out of flow times.

For more, see Match people and teams from your tools.

3. Choose how code affects effort

Who: your Engineering lead and Finance lead, together.

1. Open the Effort blend step.
2. Leave Blend GitHub into effort on (the default), or turn it off.
3. Leave Commit-timestamp attribution off (the default), unless you've agreed to turn it on.

Commit-timestamp attribution changes your CapEx and R&D figures

Turn it on deliberately, with your Finance lead. See Choose how GitHub shapes effort.

4. Check it's working

1. Open the Verify health step.
2. Check the status is Healthy and Backfill shows Completed with a date.

If the status isn't healthy, the step says why:

It says	What to do
History has never been backfilled	Select Run backfill.
A backfill is currently running	Wait. Progress shows how many repositories are done.
The last backfill failed	Read the error under Backfill, then select Run backfill again.
Some webhooks failed to process	In GitHub, check the app is still installed and the repositories are still selected.
Contributors are still unmapped	Go back to step 2.

What happens next

• Insights → Engineering insights fills with the imported pull requests.
• With Blend GitHub into effort on, matched people's code shapes the effort estimate from the next daily update. Rows show GitHub activity or Tickets + GitHub.
• Each day, Flowstate re-checks recent pull requests that aren't tied to a ticket, so one whose ticket arrives later is linked then.

If something's not right

Nothing is showing yet. History is still being imported. Wait until Verify health no longer says "A backfill is currently running". Effort changes from the next daily update.

Pull requests are missing. The repository isn't selected in the app, or history hasn't been imported. In GitHub, change the app's repository access to All repositories, then select Run backfill.

Someone's GitHub activity is missing. Their GitHub account isn't matched to them, or the app isn't installed on their repositories. Match them (step 2), and check the app's repository access.

A pull request has no cost. Its author isn't matched, it's from a bot, or it was written by an agent and Flowstate can't tell who ran it. See Agent pull requests and operators.

I can't select Connect. You need access to manage integrations. Ask your Flowstate admin.