Linkwright

Linkwright for Jira — user guide

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

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.

  1. Jira settings (⚙) → Marketplace apps → Git sync health.
  2. Click Connect a GitHub organization, then allow access to GitHub.
  3. Click Connect a GitHub organization again: your installations are listed.
  4. 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:

  1. 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.
  2. 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.
  3. 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

  1. In the Jira project: Space settings → Apps → Git repositories (“Project settings” on sites that still use that name).
  2. Repositories of connected installations (§2.3) are listed; no others ever appear.
  3. 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

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, #transition in 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:

4. What the panel shows

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

7. Data

8. Troubleshooting

The repository does not appear in Git repositories.

  1. Is the GitHub account or organization connected to this site (§2.3)?
  2. 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.

  1. 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)?
  2. Is the repository attached to this project?
  3. 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).
  4. Click Refresh in Git repositories, then reload the issue.
  5. 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.