GitHub-backed projects

Link a repository

Choose Add a GitHub repo in the New project wizard, or fill in the GitHub repository field when editing a project. Each issue gets a task that is its copy, so boards, lists and searches work as for any other project.

Same numbers, dates and authors as GitHub

A task that copies an issue has the issue’s number: issue #42 of a project with the key WEB is WEB-42, so the numbers people quote on GitHub find the same work in ShipIt. Tasks made before the repository was linked keep their numbers unless an issue needs it, and then move to the next free one. New tasks created in ShipIt open an issue and take its number.

The copy also keeps the issue’s created and updated dates, so sorting and the date filters match GitHub, and its reporter is the person who opened the issue (a placeholder when nobody in the workspace has their GitHub login yet).

Connect your GitHub account

The sync and every change you send to GitHub use your GitHub token. Opening a GitHub project without one offers to connect; you can also do it under Settings > GitHub. The token stays on your device. Without a token you still see the project’s copy of the issues (maybe not the latest), and you can vote and use boards; creating, editing, assigning, deleting and commenting are not offered. “Do not ask me again” turns the prompt off for that project on that device.

How the sync works

• Opening the project reads the issues and comments changed on GitHub since your last sync. New open issues become tasks, and GitHub wins on title, description, open or closed, labels (tags), assignees and comments.
• The first sync brings in the open issues only. Closed issues show up when you search for them in Add tasks to this board, and adding one makes its task.
• Opening a task reads its issue and all its comments.
• It runs in the background and picks up where it stopped if interrupted. Unchanged data costs nothing against GitHub’s rate limit.

Changes go to GitHub first

A new task opens an issue; an edit edits it (refused if someone changed it on GitHub since you opened it). Moving a task to a done status closes the issue and moving it back reopens it. Tags set labels, assignees set assignees, deleting closes the issue as not planned, and comments are posted, edited and deleted on the issue.

Images from issues and comments are copied into ShipIt once, so they show without a token, from private repositories too.

People

GitHub users become people in the workspace: issue authors, assignees and comment authors without an account show as their @login, and when that person links their GitHub login (or signs in and connects GitHub), their placeholder merges into them.

Import without linking

A regular project can also Import from GitHub (project menu): a one-time copy of a repository’s issues, with their comments and images, without keeping them in sync. Running it again skips the issues already imported.