Alpha GitHub Sync
Link a GitHub repository to a project so branches, commits, and pull requests automatically move tasks and build an activity timeline
GitHub Sync
Connect a GitHub repository to a project and your development activity keeps the board up to date by itself. When a branch, commit, or pull request mentions a task, Alpha moves that task through its workflow and records what happened on the task's Activity timeline, with no manual status dragging required.
How tasks are matched
Tasks are linked by their number (for example ALPHA-12). Alpha scans branch names, commit messages, and pull-request titles/bodies for any task number and applies the activity to the matching task. This is the same convention used by tools like Jira smart commits.
git checkout -b feature/ALPHA-12-add-login
git commit -m "ALPHA-12 add login form"Both the branch and the commit above reference ALPHA-12, so that task is updated automatically.
Status transitions
| GitHub event | What happens to the task |
|---|---|
| Branch created referencing a task | To Do → In Progress |
| Commit pushed referencing a task | To Do → In Progress |
| Pull request opened / reopened | → In Review |
| Pull request merged | → Done |
| Pull request closed without merge | → In Progress |
Transitions are forward-leaning, so stray activity never regresses finished work:
- Branches and commits only nudge a task out of
To Do; a task already inIn RevieworDonestays put. - Only a real merge marks a task
Done. A pull request that is closed without merging sends the task back toIn Progress.
Every event (including ones that don't change the status) is added to the task's Activity timeline, so you always see the full history of branches, commits, and pull requests alongside comments.
Connecting a repository
Connecting requires the Update Projects permission and a GitHub account with admin rights on the repository (needed to register the webhook).
- Open a project and go to its Settings tab.
- Under GitHub, click Connect GitHub and authorize Alpha.
- Choose the repository to link.
When you link a repository, Alpha automatically registers a webhook on it (for create, push, and pull_request events). From then on, activity flows in live. Unlinking the repository removes the webhook again.
If webhook registration fails (for example, you lack admin rights on the repo), the repository is still linked for browsing recent commits, but live task sync stays off until a user with sufficient rights re-links it.
The activity timeline
Open any task to see its Activity timeline. GitHub events appear attributed to GitHub, with a self-contained description such as:
Branch \feature/ALPHA-12-add-login` created by @octocat`Commit \a1b2c3d`: add login form on `main` by @octocat`Pull request #42 opened: ALPHA-12 add loginPull request #42 merged
Pull requests are also added to the task's Links so you can jump straight to them. You can add manual comments to the same timeline at any time.
Notes
- The assignee is notified when a GitHub event changes a task's status (respecting their notification preferences).
- A repository's
owner/reponame is globally unique, so each webhook delivery resolves to the correct tenant and project automatically. - Deliveries are authenticated with a per-repository HMAC secret; unsigned or mismatched deliveries are rejected.