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

• 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.

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).

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 → 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.

The installation’s repositories are read immediately, then every hour: a repository added to the GitHub App later appears without anything being pushed to it.

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: Project settings → Apps → Git repositories.
2. Repositories of connected installations (§2.3) are listed; no others ever appear.
3. Click Attach to [PROJECT KEY].

When a repository is attached, the app creates its webhook to your Jira site automatically. If it cannot, a red message says so: the repository stays attached, but its activity may not arrive until the problem is fixed.

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.

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.
• 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 sent to the native panel trigger the smart commits and automatic transitions configured in your Jira, as Atlassian’s integrations do.

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-42 or CHK-42x do not.
• CHK-42-7 is not recognized anywhere: too close to a version number. In a branch name, chk-42-add-login works, 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.

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 the current hour.	Nothing: resumes automatically.
Failing	Several consecutive failures; the reason is shown.	Read the reason; if it persists, contact support.
Not authorized	GitHub refuses access to the repository.	Check the GitHub App is still installed and still has access to this repository.
Webhook down	The periodic check found changes no webhook announced.	Check the repository’s webhook on GitHub: recent failed deliveries.

Webhooks bring activity within seconds. On top of that, the app re-reads each attached repository regularly (about every 20 minutes) to catch anything that might have been missed.

Refresh

The Refresh button (in Git repositories) re-reads the repository from GitHub immediately. The message “Check started” appears; the result arrives a few seconds later — reload the page to see it.

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.

6. Limits of this version

• GitHub only (github.com). GitLab is planned for a later version.
• Activity before attachment: commits on the default branch (the 100 most recent), pull requests (the 100 most recently updated) and branches are caught up; a commit pushed before attachment on another branch is not linked.
• 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.
• 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.
• Read from GitHub: only the repositories the GitHub App can access, read-only.
• Sent to Jira’s Development panel (Atlassian API, on your site): the same information about commits, branches, pull requests and deployments.
• 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.

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 the hour.

A commit does not appear on the issue.

1. Is the key written in upper case in the message (CHK-42)?
2. Is the repository attached to this project?
3. Was the commit pushed before attachment, on a branch other than the default one? It will not be caught up (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: saad@linkwright.io — answered by the developer who wrote the code, in English or French.