Progress

Connecting GitHub to project management is a ten-minute install followed by a few decisions that determine whether the data is any good. This guide takes you through both. When you finish, your branches, pull requests, and merges will link to tickets and move them through your workflow without anyone editing a status by hand. Before you start, make sure you have admin access to your GitHub organization, admin rights in your project management tool (Linear, Jira, or similar), and a ticket ID convention your team will actually follow. If you don't have a convention yet, Step 3 helps you create one.

Step 1: Decide what the connection should do for your team

An integration is only a pipe between two systems. What flows through it depends on what you ask for, so start by choosing the two or three outcomes that matter most. The usual candidates:

Auto-link pull requests and branches to the tickets they belong to.
Auto-move ticket status when a PR opens, goes into review, or merges.
Give leaders a view of work in flight without asking developers for updates.

Next, set the scope. List the GitHub repositories and the project management teams or projects that should be included. Start with one active team and the repos it ships from. A small scope lets you see quickly whether the conventions work, and it keeps cleanup small if they don't.

The common mistake is connecting everything at once. Org-wide installs pull in archived repos, forks, experiments, and legacy projects, and all of it lands in your data as noise. Reports then show stale branches and dead tickets that someone has to sort out by hand.

Finally, write down your workflow states exactly as they exist in your tracker today, for example Todo, In Progress, In Review, Done. Include any extras such as Blocked or Ready for QA. In Step 4 you will map each state to a pull request event, and that is much easier with the list in front of you. If your states are inconsistent across teams, fix that for the pilot team now rather than encoding the inconsistency into automation.

Step 2: Set up permissions and the GitHub integration

Both Linear and Jira offer native GitHub integrations, and you should use the official one rather than a third-party webhook script. Menu names and install screens change, so check your tool's current documentation. As of October 2026, the path is typically through the integrations or apps section of your workspace settings.

Sign in to GitHub as an organization owner in the same browser session.
In your project management tool, open the integrations settings and choose GitHub (in Jira, this is the GitHub app from the Atlassian marketplace).
When GitHub prompts you, select the organization you want to connect.
Choose Only select repositories instead of all repositories, and pick the repos from your Step 1 scope.
Approve the requested permissions and finish the flow back in your project management tool.

Selecting repositories individually follows least privilege: the app can only read what you have decided it needs. You can add repos later as the rollout widens, which is far easier than removing access after the fact.

If the install stalls, the usual cause is that a non-owner started it. GitHub requires an organization owner to approve app installations, so the request sits pending until an owner acts. Ask an owner to open the organization's settings in GitHub, go to the installed or pending GitHub Apps section, and approve the request. Then return to your project management tool and retry.

Before moving on, confirm the connection shows as active in your tracker's integration settings and that the repositories you selected are listed. If a repo is missing, fix it now. A repo that isn't in scope silently produces unlinked PRs later, and the symptom looks like a naming problem when it is really an access problem. Once the connection is live, a good GitHub integration analytics platform can start turning that activity into insight.

Step 3: Agree on a naming convention that links work to tickets

The integration finds the connection between code and tickets by reading ticket IDs. If the ID isn't in the right place, nothing links. Decide where your team will put it, then confirm that your tool detects that format. Both Linear and Jira can match IDs in branch names, PR titles, and PR descriptions, but check current docs for the exact formats supported.

A branch name such as feature/ENG-123-add-sso is the most reliable option, because the ID is there from the first commit. Many tools can copy a branch name straight from the ticket, which removes typing errors entirely.

Magic words versus plain references

Keywords in a PR description change what happens on merge. Linear supports magic words such as "Fixes ENG-123" or "Closes ENG-123," which move the ticket to done when the PR merges. A plain reference like "Part of ENG-123" only creates the link and leaves status alone. Jira handles this through its own smart commit and automation rules, so check how yours behaves.

The practical rule: use a closing keyword when the PR completes the ticket, and a plain reference when it is one piece of a larger one. Write that rule down, because getting it wrong in either direction produces tickets closed too early or never closed.

Make the convention a prompt

Add a pull request template to each repo in scope, with a line such as "Ticket: " near the top and a one-line reminder of the keyword rule. A template turns the convention into a prompt rather than a memory test.

One mistake to avoid is a single PR covering several tickets. Status automation becomes ambiguous: should all of them move, or only one? Ask developers to split the work, or to link the primary ticket and mention the others in prose.

Step 4: Map pull request events to ticket status automation

This is where your workflow list from Step 1 pays off. Open the integration's automation or workflow settings and map each pull request event to a state. A common starting set:

Branch created or draft PR opened: In Progress
PR marked ready for review: In Review
PR merged to the main branch: Done

Linear exposes these as per-team settings for branch and PR events, and Jira reaches the same result through its automation rules. Exact labels differ, so follow your tool's current documentation.

Decide what Done means

Merged is not always done. If your team merges to main and deploys later, or code waits in staging for a release window, merge-to-Done overstates progress. In that case map merge to a state like Merged or Ready for Release, and let a deployment event or a manual step close the ticket. If you deploy on every merge, merge-to-Done is accurate and simpler.

Handle the edge cases

Draft PRs: decide whether a draft counts as In Progress or does nothing. Treating it as In Progress is usually right, since work has clearly started.
Reverted merges: a revert does not typically reopen the ticket on its own. Agree on who moves it back, or open a new ticket for the fix.
Non-default branches: PRs into a release or feature branch may not trigger the merge rule. Check whether your tool limits automation to the default branch, and whether that suits your branching model.

Before enabling anything team-wide, test the rules on a single throwaway ticket. A wrong mapping applied to a whole team means dozens of tickets in the wrong state.

Step 5: Test the flow end to end with a real ticket

The throwaway ticket proved the rules fire. Now run a realistic ticket through the whole path, ideally one a developer is about to work on anyway. Work through this checklist and confirm each result before moving to the next item:

Create the ticket and assign it.
Create a branch from the ticket, using the copied branch name.
Push a commit and open a draft PR. Confirm the ticket moved to In Progress and shows the linked PR.
Mark the PR ready and request review. Confirm the move to In Review.
Approve and merge. Confirm the ticket reaches the state you mapped for merge.

Also check both sides of the link. The PR should show the ticket reference, and the ticket should show the PR, branch, and status. Reviewers need to jump from one to the other without searching.

When something fails, the cause is usually one of two things:

PR not linking: the ticket ID is malformed (wrong prefix, a typo, a missing hyphen), or the repo isn't in the integration's selected repositories.
Status not changing: a gap in the workflow-state mapping, such as an event with no state assigned, or a ticket in a team whose automation settings differ from the one you configured.

Fix each problem now, while only one person is affected. Then write a short how-to for your team channel: the branch naming rule, where the ID goes, the keyword rule, and one concrete example from the test you just ran.

Step 6: Roll out to the team and audit for gaps

Announce the change with the reason attached: developers stop writing status updates because their code does it for them. People follow conventions that visibly save them work. Pair the announcement with the PR template and the branch-name hint from Step 3 so the right behavior is the easy one.

Give it two weeks, then audit. Look for two kinds of gaps:

Orphaned PRs: merged pull requests with no linked ticket.
Ghost tickets: tickets sitting in In Progress with no linked branch or PR activity.

Orphans usually point to a missed convention, a repo with no template, or work that never got a ticket. Ghost tickets often mean the work is stalled, or being done under a different ticket. For a deeper look at the first problem, see this guide on how to find and fix stalled pull requests in GitHub.

If the misses persist, consider a lightweight CI check or bot that comments when a PR has no ticket ID. Keep it a nudge, not a required check. A hard block will eventually collide with an urgent hotfix at 2 a.m., and people will learn to game it with fake IDs, which is worse than no ID.

Track link coverage: the percentage of merged PRs that are linked to a ticket. It measures the health of the integration itself, separate from how the team is performing. Set a target that fits your work. A team that ships many small chores will land differently from one with tightly planned projects, so don't borrow an industry number. Measure your baseline from the audit, pick a target slightly above it, and review it regularly.

Step 7: Turn the linked data into signals leaders can act on

With PRs and tickets linked, the data can start answering leadership questions: what has stalled, where change is piling up, which initiatives are slipping against plan. A dashboard of counts and charts can show this, but someone still has to read it, compare it to last week, and decide what it means. That interpretation step is where most teams stop.

Progress, an AI-native engineering intelligence platform, ingests data from Linear and GitHub and does that analysis for you. It pre-computes stalled-work flags, deployment risk based on merge volume and code churn, initiative and work-stream health, and team momentum, meaning whether work is accelerating or slowing. You get assessments instead of raw charts. If you're weighing options, this roundup of engineering analytics tools shows how the category compares.

You can also ask questions in plain language through Progress's MCP server or Claude integration. For example, you might ask which initiatives have had no merged work this week, or where change pressure is highest ahead of a release. The answers come from your actual activity data rather than a generic summary.

The quality of those answers depends on the work in Steps 3 to 6. If a PR isn't linked to a ticket, it can't be tied to an initiative, so the initiative looks quieter than it is. If statuses are mapped loosely, stalled-work flags fire on the wrong tickets or miss real ones. When outputs look thin or surprising, check link coverage first, before questioning the analysis. Often the fix is a missing template in one repo or a team whose automation was never configured. Linked data is also what makes it possible to track engineering initiatives accurately from code activity.

Keeping the connection honest after the first month

Come back after a couple of sprints and recheck two things: link coverage against the target you set, and status accuracy, meaning whether tickets in each state match what is happening in the code. Tighten whichever conventions are slipping. That might mean adjusting the PR template, fixing a mapping, or bringing another team into scope now that the pilot is stable.

Once the data holds up, build on it: regular reporting, release risk reviews, and initiative check-ins that draw on connected activity instead of status meetings. Learn more about our services

How to Connect GitHub to Project Management (and Keep the Data Trustworthy)