# GitHub Integration
Link a GitHub repository to a Team Project and the task becomes the single place to see everything that happened in GitHub for it: branches, commits, pull requests and issues, tracked automatically or attached with a pasted link. Statuses can also move on their own when your team ships.
See also: [[Managing Team Tasks]] and [[Setting Up a Team Project]].
## Connecting a repository
![[team-github-connect.png]]
From the project's **Settings → GitHub** tab (owner-only), install the Zaphiri GitHub App on your GitHub account or organisation if you haven't already, then connect the repos you want tracked for this project.
- **Reuse an existing installation**: If you already manage a Zaphiri GitHub App installation through another Team Project, a new project can connect repositories from it without installing the App again
- **Connect more than one organisation**: If your team's code is split across multiple GitHub organisations, install the App on each and connect them all to the same project. Use **Connect another organization** in GitHub settings to add more
- **Grouped by organisation**: Once more than one organisation is connected, the repo list groups by organisation so it's clear where each repo lives
- **Multi-repo accounts**: If an organisation has several repositories, enable the specific ones you want tracked
- **Disconnect and reconnect**: Disconnecting a repo doesn't lose its history. Use **Reconnect** to re-link the same repo, even if every repo on the project was disconnected
- **Revoked connections stay visible**: If a repo connection is lost outside Zaphiri, for example because the GitHub App is uninstalled or repo access changes, it shows up under **Previously connected** with a **Reconnect** button, instead of just disappearing
- **Bring in the history**: A newly connected repo can backfill its existing branches, commits, and pull requests, so tasks show the work that happened before the integration was set up
> [!tip] Owner-only setup
> Connecting, disconnecting, and reconnecting a repo requires project owner access, the same permission level used elsewhere in [[Setting Up a Team Project|project settings]].
## Creating a branch from a task
Once a repo is connected, open any task and use the **Quick Start** panel to create a branch for it in one click.
- Branches are named automatically from the task's short ID and title (for example `TU-4287f447-fix-login-redirect`)
- Project owners can customise the **branch name template** in GitHub settings, so generated names follow your team's own convention
- Each task has one live branch at a time. Creating a branch again adopts the existing one instead of creating a duplicate
- The branch appears on the task immediately, ready to check out and start working
- A ready-to-copy commit template stays visible after the branch exists, so the task ID remains close at hand throughout the work
## Pull requests on the task
Pull requests that reference a task appear as cards in the task's GitHub panel, so review state is visible without leaving Zaphiri.
![[team-github-task-panel.png|574]]
- **Automatic linking**: Include the task's ID anywhere in a PR title, PR description, or branch name and the PR attaches itself to the task
- **Live PR cards**: Each card shows the author, reviewers, source and target branches, line changes, and the PR's current state (open, draft, merged or closed), kept up to date as the PR moves
- **Zaphiri comments back**: When a PR links to a task, Zaphiri posts a comment on the PR pointing back to the task, so reviewers on GitHub can find the context too
- **Pull requests in List view**: A pull request column is available in [[Team List|List view]], so you can scan review state across the whole project
One commit or PR can reference several tasks, and it links to all of them. Task IDs imported from ClickUp keep working: legacy ClickUp IDs on imported tasks are recognised alongside Zaphiri IDs.
## Attaching any GitHub link
The push webhook can't see everything: a commit from before the integration, a PR in a repo you just connected, an issue that relates to the task. **Add GitHub link** covers those.
- **Paste any GitHub URL**: Use the quiet link field at the bottom of the GitHub section to attach a commit, branch, pull request, or issue with its full detail
- **Unlink any item**: Every linked item has a menu to copy its link, open it on GitHub, or unlink it from the task
You can also go the other way: create a **pull request** or a **GitHub issue** directly from the task, pre-filled from the task's branch and name.
## Status automation
Move a task's status straight from your commit message, branch name or pull request, without switching tabs.
- Add the new status in square brackets right after the task ID, for example `TU-4287f447[in progress]` in a commit message or PR title
- The status name matches your project's own status list
- Works from commit messages, branch names, and PR titles and descriptions
> [!tip] Ship and update in one line
> `git commit -m "TU-4287f447[testing] fix login redirect"` pushes the fix and moves the task to Testing in one step.
## Git activity and notifications
Once a repo is connected, Zaphiri tracks GitHub activity for the project's tasks automatically:
- **Branches** created against the connected repo that match a task's ID
- **Commits** pushed to those branches, with per-commit stats (files and lines changed)
- **Pull requests** opened, reviewed, merged, or closed against linked tasks
Everything lands in the task's GitHub panel and its **activity feed**, newest first. It is a running record of the code activity behind the task, without anyone having to paste in a link.
- **Repository context**: The connected repository stays visible above its task activity
- **Commit timeline**: Recent commits use a compact vertical history with file and line-change totals, while earlier commits remain available through **Show more**
- **GitHub logins map to team members**: Activity shows the Zaphiri member behind each GitHub login, so the feed reads like your team, not a list of usernames
- **Notifications**: New git activity on your tasks generates [[Team Notifications|notifications]], collapsed so a burst of commits arrives as one entry
> [!success] The task shows the real state of the work
> Once a repo is connected, a task's GitHub section reflects what's actually happening in your codebase: branches created, commits pushed, pull requests reviewed and merged. It stays current automatically as your team works.
## GitHub link previews
Paste a github.com link into a task description, comment, or [[Project Docs|Project Doc]] and it renders as a live preview chip showing the PR number and its current state, visible without opening GitHub.
- Previews resolve only for repos connected to the project, so nothing leaks across projects
- When pasting, choose whether the link stays a plain URL or shows as a preview. Plain URL is the default
- The chip updates with the item's real state, so "merged" in a comment written last week still means merged
---
**Next:** See how a task holds everything else the team needs in [[Managing Team Tasks]].