Zentrik + GitHub
Bring delivery into product context. Install the Zentrik GitHub App, then reference an idea in a pull request to link the work that delivers it, so your roadmap shows what is in flight and what has shipped, next to the decision that started it.
Zentrik connects to GitHub with a GitHub App installation. The connection is read-only: Zentrik reads selected repository metadata, pull requests, branches, and commit status using short-lived installation tokens generated server-side.
Beyond showing status, Zentrik links each pull request to the idea or initiative it delivers. You make that link with one line in the pull request, and Zentrik keeps it current from webhooks. There is no board to maintain and no status column to drag: your roadmap shows what is in flight and what has shipped, beside the reasoning that started the work.
Connect GitHub
Workspace admins connect GitHub from Settings → Integrations → GitHub.
Install GitHub App
- Open Settings → Integrations → GitHub.
- Choose Connect GitHub.
- GitHub opens the Zentrik GitHub App installation flow.
- Choose the organization or account.
- Select the repositories Zentrik should read.
- Choose Install & Authorize.
- GitHub redirects back to Zentrik and starts reading the selected repositories.
Select repositories
Select repositories in GitHub during installation. Zentrik summarizes the installed repositories immediately after you return.
If a workspace should focus on one installed repository, use the repository focus fields on the GitHub integration detail page. Zentrik verifies that the installation can read that repository before saving the focus.
Link work to ideas
Zentrik links a pull request to an idea or initiative when you reference it somewhere you control: a Zentrik: trailer line in the description, or the branch name. A passing mention in prose or in the title does not create a link, so quoting an idea id in a sentence never mis-files your work.
Reference an idea in a pull request
Add a trailer line to the pull request description. It starts with the Zentrik: marker, followed by the idea reference:
Zentrik: closes IDEA-42You can reference more than one idea on the same line, which is how a single pull request can deliver several of an initiative's ideas:
Zentrik: closes IDEA-42, IDEA-57Every idea in Zentrik shows its exact reference (for example Zentrik: IDEA-42), so you can copy it straight into the pull request.
Close it or relate it
The verb after Zentrik: sets what the link means.
| You write | Zentrik treats the pull request as |
|---|---|
Zentrik: closes IDEA-42 | work that completes the idea |
Zentrik: relates IDEA-42 or Zentrik: IDEA-42 | work that touches the idea, without finishing it |
Closing verbs are close, fix, resolve, complete, and deliver (and their tenses, such as fixes or resolved). Anything else, or no verb at all, relates.
Only a shipped closes link asks Zentrik to suggest that an idea is done. A related pull request never marks work complete on its own, so a change that merely touches an idea cannot close it by accident.
Reference from a branch
A branch whose name contains the idea, such as jab/idea-42-timeline, also links the pull request.
Branch references always relate. You cannot close an idea from a branch name, because a branch is a place to work, not a statement that the work is finished. Use the Zentrik: closes trailer when you want the pull request to complete an idea.
Link by hand
You do not have to use a reference. You can link or unlink a pull request directly from the Delivery tab on an initiative, or the Development panel on an idea.
If Zentrik proposes a link you do not want, reject it. Zentrik remembers the rejection and will not suggest the same link again.
See delivery in Zentrik
Once a pull request is linked, delivery appears next to the work, not in a separate tracker.
Where delivery shows
- On an initiative, the Delivery tab lists its linked pull requests and their state. The tab unlocks once GitHub is connected.
- On an idea, the Development panel shows the same for that idea.
- On Home, work with open pull requests appears as in delivery.
Zentrik advances status from facts and leaves judgments to you. The first open pull request linked to an initiative moves it to In progress automatically. Marking the work complete stays a suggestion: whether the work satisfied the decision is your call, so Zentrik never closes an idea for you.
Merged vs shipped
A merge is not the same as reaching customers. If your repository promotes work through a delivery branch (for example develop) into a production branch (for example main), Zentrik reads that pattern from your release history and separates the two states:
- Merged work is pre-production until a release promotes it.
- Only work that reached the production branch reads as shipped.
Zentrik suggests completing an initiative only when its closing work has shipped to production. For repositories without a promotion flow, merged means shipped.
Get the most out of it
- Add the
Zentrik:line to your pull request template so every pull request references its idea by habit, without anyone remembering to. - Use
closesfor the pull request that finishes an idea, andrelatesfor supporting work. Precise intent keeps completion suggestions meaningful. - Reference an initiative's ideas from the pull requests that deliver them. The initiative rolls up delivery from its ideas, so you do not reference the initiative directly.
- Treat completion suggestions as a prompt to confirm, not a step to skip. Status moves on facts; whether an idea is truly done stays your decision.
For workspace admins
- Reconnect GitHub if the GitHub App is uninstalled, repository permissions change, or the selected repositories need to change.
- Update the focused repository from the integration detail page when the workspace should follow one installed repository.
- Keep the GitHub App permissions read-only: metadata, contents, pull requests, commit statuses, and checks.
Troubleshooting
Most connection problems clear up after a fresh authorization or an admin allows the app. If you have tried that and still cannot connect, contact us and we will help.
A pull request did not link to its idea
Confirm the pull request description has a Zentrik: trailer line, or that the branch name contains the idea reference. A mention in the title or in prose alone does not link. Check that the reference matches the idea, for example IDEA-42, and that the idea belongs to the same workspace as the connected repository.
An initiative is not suggested as complete
Completion is suggested only when a closes pull request has shipped. A relates pull request never triggers it. If your repository promotes to production, the closing work must reach the production branch first; merged-but-not-promoted work stays pre-production.
Installation succeeds but repository focus fails
Confirm that repository is included in the GitHub App installation. Organization owners can update the selected repositories from GitHub.
Home does not show GitHub status
Open Settings → Integrations → GitHub and confirm the GitHub App installation includes at least one repository.
Still stuck
Contact us and we will help troubleshoot the workspace connection with you.