Docs / Integrations
GitHub
Link your repositories to a project. Pull requests that mention a ticket key show up on that ticket with their live status — and can move the ticket for you when they merge.
Overview
Planytic connects to GitHub through the Planytic GitHub App. It only reads pull requests — titles, authors, branches and status. It never reads your code, never writes to your repositories and never comments on pull requests.
- A project can link several repositories (for example a frontend and a backend).
- Each repository belongs to one project, so a pull request never shows up twice.
- Pull requests are linked from the moment you connect; older ones can be pasted in by link.
Connect a repository
Open the project's GitHub settings
In a project, go to Settings → GitHub and choose Connect GitHub.
Install the app on GitHub
Pick your account or organization and the repositories Planytic may see, then authorize. GitHub sends you back to Planytic. Organization members without owner rights can request the install; an owner approves it on GitHub.
Pick the repositories
Choose the GitHub account, then Link each repository this project uses. Repositories already linked elsewhere are labelled.
Already installed the app?
Use Already installed? Sync from GitHub instead of Connect. It only asks GitHub which installations you can manage and lists them — no reinstall.To add repositories later, use Add account or repositories. Disconnecting a repository stops new links; pull requests already on tickets stay there.
Linking pull requests
Mention a ticket key anywhere in the pull request's branch name, title or description:
| Where | Example | Links to |
|---|---|---|
| Branch | feat/XA-12-login | XA-12 |
| Title | Fix login redirect (XA-12) | XA-12 |
| Description | Closes XA-12 and XA-14 | XA-12, XA-14 |
- Keys are case-insensitive and matched as whole words —
MAX-1never linksXA-1. - One pull request can link several tickets; a ticket can have several pull requests.
- Removing a key from a title later doesn't unlink it — only unlinking by hand does, so links don't flicker while people edit.
- Moved a ticket to another board? Its old key still links: ticket numbers are unique per project.
Link by hand
Open a ticket and use Development → Link pull request, then paste a link like https://github.com/acme/web/pull/123. The repository must be linked to the project.
On tickets and cards
Each ticket has a Development section listing its pull requests with their state, author and branch. Board cards show a small pull-request icon — with a count when there are several:
| Icon colour | Meaning |
|---|---|
| Green | Open |
| Grey | Draft |
| Purple | Merged |
| Red | Closed without merging |
If any pull request on a ticket is still open, the card shows open — the work isn't finished even if another one merged. Everything updates live as GitHub reports changes, and the ticket's activity shows entries like “linked PR acme/web#12” by GitHub.
Filter for them with search: has:pr, pr:open, pr:merged.
Automation
Tickets can move by themselves as their pull requests change. Rules are set per board in Settings → Boards → GitHub automation, because every board has its own columns.
| When a pull request is… | Default | Typical choice |
|---|---|---|
| Opened, reopened or ready for review | Don't move | Code Review |
| Converted to draft | Don't move | In Progress |
| Merged | Done (or the board's last column) | Done |
| Closed without merging | Don't move | To Do |
- Several pull requests on one ticket: “merged” waits until every one is merged or closed, so a frontend PR merging alone doesn't finish a ticket whose backend PR is still open.
- Each board has an on/off switch. Off pauses it without losing its rules.
- Moved cards go to the bottom of the column, live for everyone, logged as moved by GitHub.
Permissions
| Action | Who |
|---|---|
| Connect, link or disconnect repositories | Project owners and admins |
| Change automation rules | Project owners and admins |
| Link or unlink a pull request on a ticket | Anyone who can edit tickets |
| See pull requests on tickets | Everyone in the project, and AI agents with tickets:read |
Connecting only lists GitHub accounts you have proved you can manage — Planytic checks with GitHub, so nobody can link someone else's repositories.
Self-hosting: the GitHub App
Running your own Planytic server? Create a GitHub App once (GitHub → Settings → Developer settings → GitHub Apps):
| Setting | Value |
|---|---|
| Callback URL | https://YOUR_API/api/v1/github/callback |
| Request user authorization (OAuth) during installation | On |
| Redirect on update | On |
| Webhook URL | https://YOUR_API/api/github/webhook |
| Webhook secret | A random string (also in GITHUB_APP_WEBHOOK_SECRET) |
| Repository permissions | Pull requests: Read-only (Metadata: Read-only is automatic) |
| Subscribe to events | Pull request (installation events are always sent) |
Then set GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY (the .pem, base64-encoded on one line) and GITHUB_APP_WEBHOOK_SECRET, run php artisan migrate, and check everything with php artisan github:check.
Troubleshooting
GitHub keeps a log of every webhook: GitHub App settings → Advanced → Recent Deliveries. The response body says what Planytic did with each one.
| You see | Fix |
|---|---|
| 401 “Invalid signature” | The webhook secret on GitHub differs from the server's (or is empty). Paste the same value on both. |
| “isn't linked to a Planytic project” | Link that repository in the project's GitHub settings. |
| “installation … isn't connected” | The app was reinstalled — use Sync from GitHub once. |
| “no new ticket keys found” | Put the key (XA-12) in the branch, title or description. |
| 404 on the callback URL | The callback URL on GitHub has a typo or trailing space. |
| Back on the homepage after installing | The callback URL points at the website instead of the API. |
After fixing a setting
Click Redeliver on the delivery in GitHub, or edit the pull request's title — no need for a new pull request.