Connecting GitHub · GitLab

Once a repository is connected to GoalTrack, you no longer move issues by hand.

• When a branch or pull request that contains an issue key (ENG-12) is opened, the issue moves to the team’s first “started” status.
• When that pull request is merged, the issue moves to the team’s first “completed” status (only for closing links — see Linking issues and pull requests).
• The Development section of the issue shows a pull request card (open, merged, closed) that takes you to GitHub or GitLab.
• The activity tab records “GitHub” or “GitLab” as the actor, with the source “GitHub/GitLab integration”.

GoalTrack only receives webhooks. It never writes anything to GitHub or GitLab (no pull request comments, no check statuses).

Who connects

Workspace owners and admins connect from Settings › Integrations. You can add a webhook to a single repository or to a whole organization (group). A workspace can have up to 20 connections.

1. Create the connection in GoalTrack

1. On the GitHub (or GitLab) card in Settings › Integrations, click Add connection.
2. Enter a connection name (for example acme/api) and choose Target teams. With target teams selected, only those teams’ issue keys are linked. For GitLab, also enter the host (default gitlab.com; use your own address if self-hosted).
3. You get a Receive URL and a Secret. 🔴 The secret is shown only once, on this screen — copy it before closing. If you lose it, use Regenerate secret on the connection row.

2-a. Add the webhook on GitHub

1. In the GitHub repository (or organization), open Settings › Webhooks › Add webhook.
2. Paste the receive URL into Payload URL.
3. Set Content type to application/json (application/x-www-form-urlencoded is accepted too).
4. Paste the secret into Secret.
5. Under Which events would you like to trigger this webhook?, choose Let me select individual events and check only Pull requests (you can uncheck Pushes, which is checked by default).
6. Click Add webhook. GitHub sends a confirmation signal (ping) right away. When the connection row on the GoalTrack card shows “Connection confirmed”, you’re done.

2-b. Add the webhook on GitLab

1. In the GitLab project (or group), open Settings › Webhooks › Add new webhook.
2. Paste the receive URL into URL.
3. Choose how requests are verified:
   • Signing token (recommended, GitLab 19.0 and later): click Generate signing token to create a token (starting with whsec_), paste it into the signing token field on the GoalTrack result screen, and click Save signing token (to do it later, use Paste signing token on the connection row). From then on the connection accepts signed requests only. Requests whose signature timestamp is more than 5 minutes old are rejected.
   • Secret token (before GitLab 19.0): paste the GoalTrack secret into the Secret token field. The token travels as-is in a request header, so it is weaker than a signature — the card marks it as “weak”. Use a signing token when you can.
4. Under Trigger, check only Merge request events.
5. Click Add webhook. GitLab does not send a confirmation signal when you save, so the connection row changes once the first merge request event arrives.

Linking issues and pull requests

GoalTrack looks for issue keys in the pull request’s branch name, title, and description. Case does not matter (eng-12 = ENG-12).

Where	Example	Link
Branch name	eng-12-fix-login	Closing — done on merge
Pull request title	ENG-12 Fix login	Closing
Description + closing word	Fixes ENG-12 · Closes ENG-12 · Resolves ENG-12	Closing
Description + reference word	Refs ENG-12 · Part of ENG-12 · Related to ENG-12	Reference — card only, status unchanged
Title or description + skip word	skip ENG-12 · ignore ENG-12	Not linked

• A key in the description without a closing or reference word is not linked.
• Copy branch name on the issue (⌘/Ctrl + ⇧ + .) gives you a branch name that contains the key.
• A draft pull request only adds the card; the issue status stays. Once it leaves draft (GitHub Ready for review, or removing the draft mark on GitLab) the issue moves to in progress.
• With several closing pull requests, the issue moves to done when a merge arrives and no other one is still open (including drafts) (pull requests closed without merging are not waited for).
• Issues already in progress, done, or canceled are never moved back. Opening a pull request does not return a done issue to in progress.
• An issue moves only when a pull request is opened, reopened, leaves draft, or is merged — or when an edit newly adds its key. If someone changes the issue’s status by hand, later pushes or title edits on the same pull request do not move it again.
• Archived issues are neither newly linked nor moved (cards already attached stay and keep following the pull request state).
• If an issue moved teams and got a new key, its old key still links.

Pull requests from outside contributors

Anyone can put an issue key in a pull request title, so a pull request from outside does not move the issue or add a card when opened. When a maintainer merges it, the card is added and the issue moves to done. Editing its title or description after the merge changes nothing (adding more keys cannot close other issues).

• GitHub: every pull request whose author is not the repository’s owner, an organization member, or a collaborator (the author association GitHub attaches to a pull request: OWNER, MEMBER, COLLABORATOR) — whether it comes from a fork or from a branch in the same repository.
• GitLab: every merge request from a fork (even when the author is a member).

Reading the connection row

Status	Meaning and what to do
Waiting	Nothing has arrived yet. Check the webhook URL and secret again.
Connection confirmed · Healthy	Events are arriving.
⚠ Needs attention	Some events arrived but could not be applied. For example: no issue key found (check that the branch or title has a key and the target teams are right), or the team has no started/completed status.
⚠ Recently rejected	The event selection or format is wrong. Check that you chose Pull requests on GitHub or Merge request events on GitLab, and that the content type is right.
Off	GoalTrack has stopped receiving.

You can also see how each delivery was handled under Recent Deliveries on the GitHub webhook screen, and send a failed delivery again with Redeliver.

Turning off · deleting · regenerating the secret

• Turn off: only GoalTrack stops receiving. The GitHub/GitLab webhook stays in place, so turning it back on resumes right away.
• Delete: the receive URL stops accepting requests. Delete the webhook on GitHub/GitLab as well (GitLab disables a webhook by itself after repeated rejections). Pull request cards already attached stay as a record and are no longer updated.
• Regenerate secret: the old value is rejected from that moment. Paste the new value into GitHub/GitLab right away. Deliveries that arrived in between can be sent again from GitHub Recent Deliveries or GitLab Recent events. For a GitLab connection that uses a signing token, resending a delivery older than 5 minutes may be rejected because of its signature timestamp.

Limits

• Each connection accepts up to 600 events per minute. Beyond that, requests are rejected with 429 and the card warns that the per-minute limit was exceeded — GitHub does not retry failed deliveries on its own, so resend them from Recent Deliveries.
• A workspace records up to 10,000 deliveries per 24 hours. Beyond that, the rest are not processed and the card shows a “log limit” warning.
• Request bodies are accepted up to 1 MiB.

Backups and exports

Git connections, pull request cards, and delivery records are not included in workspace exports or backups (so connection secrets don’t leak through a file). After restoring, connect again and pull request cards attach from new events onward.