Linkwright for Jira — user guide
On this page
Linkwright for Jira shows, on every Jira issue, the GitHub activity that concerns it: commits, branches, pull requests, reviews, merges and deployments. And it always tells you how current that information is.
1. Before you start
- Jira Cloud, and administration rights on the project concerned.
- GitHub repositories on github.com. GitLab is not supported yet.
- Permission to install a GitHub App on the GitHub account or organization.
2. Installation
2.1 Install the app in Jira
Install Linkwright for Jira on your Jira site from the Atlassian Marketplace (in Jira: Apps › Explore more apps, search for Linkwright). It is free for up to 10 users.
Not a Jira administrator? Only a site administrator can install an app. From the same page in Jira, the button sends them a request instead, with an optional message; they find it under Apps › Manage apps › Requested apps (Atlassian documentation).
2.2 Install the GitHub App and choose repositories
Install the Linkwright for Jira GitHub App on your GitHub account or organization, then choose the repositories it can access. On those repositories only, the app reads code, pull requests and deployments, and manages its own webhooks (created when a repository is attached, deleted when it is detached). It never changes code, pull requests or other webhooks of the repository. It also reads the organization’s membership, only to check that the person connecting it to Jira is an owner (section 2.3). Each permission and the reason for it: Permissions and sync statuses, explained.
2.3 Connect your GitHub account or organization to Jira (once)
Done by a Jira administrator who is also an owner of the GitHub account or organization — usually the person who just installed the GitHub App.
- Jira settings (⚙) → Marketplace apps → Git sync health.
- Click Connect a GitHub organization, then allow access to GitHub.
- Click Connect a GitHub organization again: your installations are listed.
- Click Connect to this site next to the right one.
Why the owner role is required: without it, any member of an organization could expose in Jira private repositories they cannot see themselves. An installation you do not control is listed with the reason it cannot be connected, and who can connect it instead.
Are the Jira admin and the GitHub owner two people? The admin invites the owner with a link:
- Jira settings (⚙) → Marketplace apps → Git sync health, section Is the GitHub owner someone else?: type the organization’s name, then click Create an invitation link.
- Send the link to the owner. It works once, only for that organization, and expires in 72 hours. It is shown only when created; creating another one cancels the previous one, and Cancel invitation disables it.
- The owner opens the link, installs the GitHub App if it isn’t installed yet, then authorizes GitHub and connects the organization.
Limit: the owner needs access to Jira on this site, so they use a Jira license: Atlassian doesn’t open this kind of page to people without Jira access. They don’t need to be an administrator. The page appears for every user in Jira’s Apps menu (“Linkwright: connect GitHub”); without a valid invitation it shows nothing and allows nothing.
Authorized the wrong GitHub account? Click Use another GitHub account and choose the right one.
A Get started checklist at the top of Git sync health (Get Started, in the ⋯ menu of Linkwright under Site settings › Connected apps, opens the same page) shows where the site stands: GitHub App installed and organization connected, repositories read, repositories attached. Each step is ticked from what the site actually holds; once all are done, a single line remains.
The installation’s repositories are read immediately, then every 10 minutes, and again each time an administrator opens Git sync health or a project’s Git repositories page (at most once a minute): a repository just added to the GitHub App shows up on that page within seconds, without anything being pushed to it. An installation of more than 500 repositories is read in full once an hour, so a new repository can take up to an hour to appear; the screen shows how old the last reading is. Above 5,000 repositories, the screen says the list is incomplete.
The very first screen after installing the app can take up to 20 seconds while the app prepares its database; it says so while it waits.
To disconnect an installation, click Disconnect next to it, then confirm. Every repository of that installation is detached from every project, and its webhook and its entries in Jira’s Development panel are removed within minutes. Nothing is deleted on GitHub, and the GitHub App stays installed: connect it again at any time.
2.4 Attach a repository to a Jira project
- In the Jira project: Space settings → Apps → Git repositories (“Project settings” on sites that still use that name).
- Repositories of connected installations (§2.3) are listed; no others ever appear.
- Click Attach to [PROJECT KEY].
Repositories whose recent commits cite the project’s key are listed first, marked Suggested with the number of commits; Attach the suggested repositories attaches them all at once. Suggestions are refreshed once a day per repository; they never link anything by themselves. Right after an organization is connected they are still being read, 15 repositories every 5 minutes: the page says how many so far.
When a repository is attached, the app creates its webhook to your Jira site automatically and starts reading the repository at once: its state usually turns Up to date within seconds. If the webhook cannot be created, a red message says so: the repository stays attached, but its activity may not arrive until the problem is fixed. An empty repository is fine: it is up to date with nothing in it.
Scoped per project. A repository only creates links on issues of the projects it is attached to. A commit that mentions an issue from another project is ignored there. The choice belongs to Jira: an administrator of any project can see the names of all repositories of connected organizations and attach any of them, and whoever can see that project’s issues sees the activity.
2.5 Where to see activity on an issue
- Jira’s Development panel (native): branches, commits, pull requests and deployments appear there automatically, as with Atlassian’s integrations. Boards, JQL search and Automation read the same data. On a brand-new site, Jira can take a few minutes to show the first data it received (measured: about four minutes); the app’s Git activity panel shows it as soon as it arrives.
- The app’s Git activity panel: the details, and above all the freshness of each repository. Jira does not show app panels automatically: on an issue, click the apps button under the issue title, then choose Git activity.
Commits, branches and pull requests pushed while a repository is attached trigger the automatic transitions configured in your Jira, as Atlassian’s integrations do; activity read later (first read after attaching, periodic re-read, Refresh) does not. Smart Commits (
#comment,#time,#transitionin a commit message) run too, since version 2.17 (2 November 2026), with three conditions: you wrote the commit and pushed it yourself (GitHub must have verified its email address on the account that pushed it), every issue key in the message belongs to a project the repository is attached to, and the commit arrives live. Jira then runs the command as the Jira user whose email address is the commit’s. Details and checklist: Smart Commits guide.
3. How an issue is linked to GitHub activity
The app looks for the issue key (for example CHK-42):
| Where | Example | Rule |
|---|---|---|
| Branch name | feature/chk-42-login |
upper or lower case |
| Commit message | CHK-42 Fix login |
upper case |
| Pull request title or description | CHK-42: new page |
upper case |
Details:
- The key must be a whole word:
CHK-42.and(CHK-42)work,xCHK-42orCHK-42xdo not. CHK-42-7is not recognized anywhere: too close to a version number. In a branch name,chk-42-add-loginworks, because what follows is not a number.- Only keys of projects the repository is attached to count.
- Emoji and non-Latin characters in messages do not prevent detection.
- A commit on a branch whose name contains a key is linked to that issue, even if its message cites none. A commit whose message and branch cite no key is linked to nothing.
4. What the panel shows
- Pull requests: Open, Merged or Closed, with their title.
- Reviews: Approved, Changes requested, Commented or Dismissed.
- Deployments: environment and state. A successful deployment is linked to every commit it ships since the previous successful deployment of the same environment, not only to the last commit.
- Branches: including deleted branches, marked as such.
- Commits: the 10 most recent, then the count of the others.
- At the top: the freshness of each repository attached to the project. Above 10 repositories, only those holding this issue’s links (or, if it has none, those that need attention), and the number of others.
- At the bottom: a branch name to copy, as a
git switch -ccommand. The app has no write access to GitHub: it does not create the branch.
A project administrator chooses that name’s format under Space settings › Apps › Git repositories, for
example feature/{key}-{description} or {type}/{key}-{description}. {key} is the issue key
(required), {description} what the developer types, {type} the issue type in lower case. A format
that would not link a branch to its issue, or that Git would refuse, is not accepted.
5. Sync states
Shown on the panel and in Git repositories.
| State | Meaning | What to do |
|---|---|---|
| Up to date | The last sync succeeded recently. | Nothing. |
| Never checked | Repository attached, but not yet read in full. | Wait for the next cycle (a few minutes), or click Refresh. |
| Out of date | No successful sync for more than 2 hours. | Click Refresh if the data must be current now. |
| Rate limited | The GitHub API request quota is used up for now. | Nothing: resumes automatically. |
| Failing | Several consecutive failures; the reason is shown. | Read the reason; if it persists, open a request on the support portal. |
| Not authorized | GitHub refuses access to the repository. | Check the GitHub App is still installed and still has access to this repository. |
| Webhook down | At least 3 commits appeared on the default branch with no webhook behind them: the periodic check found them, and no delivery arrived in the 15 minutes that followed. Commits from before attachment or from the first check never count. | On GitHub, open the repository’s Settings, then Webhooks: check that Linkwright’s webhook exists and is active, and read its recent deliveries. The state clears at the next delivery; if the webhook is gone, detach and re-attach the repository. Commits on the default branch keep arriving through the periodic check, later; other activity waits for the webhook (see §6). |
Webhooks bring activity within seconds. On top of that, the app re-reads each attached repository regularly (about every 35 minutes) to catch what was missed on the default branch, in pull requests and in branch names (see §6).
Under each repository, Last delivered to Jira shows the last commit Jira accepted and when (“Nothing delivered to Jira yet” if none). Search by name, or use the Needs attention and Not checked yet filters to find the repositories that are not up to date.
Refresh
The Refresh button (in Git repositories) re-reads the repository from GitHub immediately. The screen shows “Reading 0 of 1 repository…” and updates itself when the reading is done, usually within a few seconds; no need to reload. The same counter appears after a repository is attached.
It also re-sends the repository to Jira’s Development panel, rebuilding it: its commits are removed then recreated. Allow a few minutes (the next cycle, then Jira’s processing) before seeing them all on the issue again.
On a repository holding more than 400 items in Jira, Refresh re-reads GitHub but doesn’t rebuild what Jira holds, because the app couldn’t confirm the result. The screen says so.
6. Limits of this version
- GitHub only (github.com). GitLab is planned for a later version.
- Activity before attachment: on the first read after attachment, commits on the default branch (the 100 most recent), pull requests (the 100 most recently updated) and branches are caught up, plus the commits that up to 20 branches not seen yet hold beyond the default branch (250 per branch). A repository with more such branches catches up 20 more at each Refresh.
- Very large pushes: up to 10,000 commits are caught up automatically. Beyond that, catch-up stops and the failure is recorded on the repository; the remaining commits are not linked.
- First deployment of an environment: with no previous deployment, it is linked to the 100 most recent commits of the deployed version.
- Reviews and deployments arrive by webhook only: the periodic check does not catch them up.
- A webhook that missed a push on another branch: the periodic check does not read those commits. Refresh catches them up (up to 20 branches each time).
- Long deployment ranges: up to 1,000 commits between two deployments are read.
- Superseded deployment: a deployment replaced by a newer one still shows as “Deployed”.
- Native panel: a branch with no commit known to the app is not shown there (Jira requires its last commit); after a project is attached to or detached from a repository, the panel is corrected within a few minutes (the commits concerned are removed and re-created); the environment type (production, staging…) is inferred from its name. Jira shows only the first 100 commits of an issue there (a Jira limit); the Git activity panel shows them all.
- Inactive license: the panel and Git repositories show “License inactive”; GitHub activity is no longer synced until the license is renewed, then it is caught up within the limits above.
7. Data
- Stored in Jira (your site’s Forge storage, isolated from other customers): repository and branch names; commit identifiers, first line of the message, author and date; pull request title, author and reviewers; review author and state; deployment environment and state; repository sync state; the GitHub login of the person who connected an organization; the branch name format a project administrator chose. Also, for every repository of a connected organization, attached or not: its name, and how many recent commits cite each project key (for suggestions, not the commits).
- Read from GitHub: only the repositories the GitHub App can access, read-only. Attached repositories in full; the others only their 50 most recent commits, once a day, for suggestions.
- Sent to Jira’s Development panel (Atlassian API, on your site): the same information about commits, branches, pull requests and deployments. For a commit with a Smart Commit command, its full message and author’s email address are also sent, and not stored.
- No Jira data is ever sent to GitHub.
- Full privacy policy: published with the Marketplace listing.
8. Troubleshooting
The repository does not appear in Git repositories.
- Is the GitHub account or organization connected to this site (§2.3)?
- Does the GitHub App have access to this repository? A repository added to the GitHub App appears within 10 minutes.
A commit does not appear on the issue.
- Is the key in the commit message, in upper case (
CHK-42), or in the name of the branch the commit was pushed to (feature/chk-42-login, any case)? - Is the repository attached to this project?
- Was the commit pushed before attachment, on a branch other than the default one? Refresh catches up the commits of up to 20 branches not seen yet (see §6).
- Click Refresh in Git repositories, then reload the issue.
- Still missing? The full checklist covers Jira’s indexing delay, cached counts and the JQL checks.
The panel does not appear on the issue. Add it with the apps button under the issue title (§2.5).
“Repository attached, but its webhook could not be created”. Check that the GitHub App has access to this repository and permission to manage its webhooks, then detach and re-attach the repository.
Support: support@linkwright.io — answered by the developer who wrote the code, in English or French.