GitHub
Link a project to a GitHub repository so labelled issues become tasks, stay in sync both ways, and merged pull requests finish the tasks they name.
Team plan and aboveFor owners and admins
Link a project to a GitHub repository and the issues you label projik become tasks in that project. The task and the issue then stay in step: rename or close one and the other follows. A pull request that names a task is listed on it, and merging the pull request finishes the task.
Owners and admins connect GitHub, link repositories and run a sync. Everyone in the workspace can see which repository a project is linked to and when it last synced.
Connect GitHub#
A workspace has one GitHub connection, to one GitHub account or organisation.
- Open Integrations in the sidebar.
- On the GitHub card, choose Connect.
- On GitHub, pick the account or organisation and the repositories Projik may use, then install.
- You come back to Integrations, and the card shows Connected.
Projik can only use the repositories you grant it. In them it reads the repository’s details and contents, reads and writes issues, and reads pull requests.
To grant another repository later, choose Re-authorise in the GitHub panel and add it on GitHub.
Link a project to a repository#
Once GitHub is connected, the Integrations page shows a GitHub panel with Connected repos.
- Choose + Connect another repo.
- Pick the Repo and the Project.
- Choose Link.
Linking imports the repository’s open issues labelled projik straight away. A project links to one repository, and a repository that’s already linked isn’t offered again. If the repository you want isn’t in the list, it hasn’t been granted to Projik yet: use Re-authorise.
You can reach the same place from a project: Project settings, then Repository & sync.
Sub-projects#
Each sub-project links its own repository, so one client with two applications can have a repository per application. A parent project can link one too, for work that’s shared. Issues, pull requests and AI workers on GitHub always use the repository of the task’s own project, never its parent’s. Connected repos lists a parent’s repositories together, each sub-project named “Parent › Sub-project”. See Sub-projects.
Choose where imported issues land#
Each linked repository has a Default outcome. Imported issues become tasks under that outcome, or under no outcome if you leave it at No outcome. For a sub-project, its parent’s outcomes are offered too. You can also change it from the bar above the project’s task list, which shows the repository, the outcome and when it last synced.
How issues and tasks sync#
| In GitHub | In Projik |
|---|---|
An open issue is labelled projik | A new task in Backlog, with the issue’s title and description |
| The issue’s title or description changes | The task’s title or description changes |
| The issue is closed | The task moves to Done |
| The issue is reopened | A task that was Done goes back to Backlog |
| In Projik | In GitHub |
|---|---|
| The task’s title or description changes | The issue’s title or description changes |
| The task moves to Done | The issue is closed |
| The task leaves Done | The issue is reopened |
| The task moves to Invited, In progress, In review or Blocked | The issue gets one label: projik:invited, projik:in-progress, projik:in-review or projik:blocked |
A few rules to know:
- Only open, labelled issues are imported. Closed issues and pull requests never become tasks.
- The label starts the link; it doesn’t hold it. Once an issue has a task, they keep syncing even if the
projiklabel is removed. - Your other labels are left alone. Projik only adds and replaces its own
projik:status label. A task in Backlog has none. - The last change wins. If the issue and the task were both edited, the side edited most recently is kept.
- Deleting an imported task stops it coming back. The issue isn’t imported again.
- Archived projects are frozen. Nothing from GitHub changes a task in an archived project.
A linked task shows an Issue row in its side panel, with a link to the issue.
When changes arrive#
Changes usually arrive within moments. Projik also checks each linked repository every 15 minutes, which catches anything that was missed. To check now, choose Sync now on the repository’s row on Integrations or in the bar above the project’s task list. The bar then says what the sync did, for example “2 imported · 1 updated”, or “Up to date”.
Tasks that open an issue#
Tasks you create in Projik stay in Projik: they don’t become GitHub issues. There are two exceptions.
- A task made from a support ticket, in a project with a linked repository, opens an issue for itself. See Ticket tasks.
- A task handed to an AI worker that works on GitHub has an issue opened for the hand-off. See GitHub workers.
Pull requests#
A pull request in a linked repository is tied to a task when it names it in one of two ways:
- A closing keyword and the issue number in the pull request’s title or description, such as
Fixes #12,Closes #12orResolves #12. - The task’s key in the pull request’s title or branch name, such as
NH-038or a branch callednh-038-fix-badge. A key only counts for tasks in a project linked to that repository.
What happens then:
- The task lists the pull request in a Linked PR row, with a link to it.
- When the pull request is merged, the task moves to Done, and its issue is closed.
- If someone changed the task after the merge, for example by reopening it, the merge doesn’t overrule them.
- Opening a pull request doesn’t change the status of a person’s task. For a task held by an AI worker that works on GitHub, an open pull request sends the task to In review.
Pixel, the AI worker that codes, uses all of this: it hands a task to the coding agent in your repository and brings the pull request back for you to review. See GitHub workers.
Unlink a repository#
On the repository’s row on Integrations, choose Unlink… and then Unlink.
- The tasks that were imported stay in the project.
- They stop syncing: changes no longer travel to or from their issues.
- If you link the project to a different repository, that repository’s labelled issues are imported fresh.
Disconnect GitHub#
In the GitHub panel on Integrations, choose Disconnect and then Disconnect for everyone.
Syncing stops for every project in the workspace. Tasks and the links between projects and repositories are kept, so syncing picks up again if you connect the same account later.
Plans#
Connecting GitHub needs the Team plan or above. AI workers that work on GitHub need Business.
If your workspace moves down to Free, a connection you already have keeps syncing, and you can still unlink or disconnect. Connecting GitHub again isn’t possible until the workspace is on Team. See Compare plans.