GitHub

Overview

Constructor's GitHub integration is a powerful way to improve your team's collaboration by:
  • Keeping your team up-to-date on development activity. Open PRs are shown right on the board on their associated ticket's card
  • Making it easy to jump between the ticket in Constructor and the PR in GitHub, and vice versa
  • Ensuring code reviewers stay on top of their pending reviews and giving them the context they need

Key concepts

Development workflow

The GitHub integration is optimized for trunk-based development. However, you can certainly use other development workflows like GitFlow or GitHub Flow, and you can change how your team works over time. All that's required is that your workflow uses pull requests to propose and review code changes.

Branch-based linking

The GitHub integration works by automatically linking pull requests to tickets using the pull request's head branch name.
For example, a pull request using branch names similar to these would be linked to ticket #123:
  • 123-foo-bar
  • 123_foo_bar
  • baz/123-foo-bar
Constructor doesn't support linking code to tickets if you push commits directly to your trunk branch. You must first push the commits to a separate branch with a name containing the ticket's ID, then open a pull request from that branch to your trunk branch.

Many-to-one-model

You can link as many pull requests as you like to the same ticket.
Some teams prefer a model where a ticket can have only one pull request. If the developer needs to make additional code changes, they make a new ticket first.
Feel free to use that model if you prefer. However, it can easily lead to an overwhelming number of tickets that obscures your team's work and hinders collaboration. Instead, we recommend being less rigid and using multiple pull requests per ticket.

Automatic CI/CD detection

If your team has connected a CI/CD tool to your GitHub repository for code quality checks, testing, builds, etc., Constructor will automatically detect it and display the live build status right on the ticket's card.
For many common CI/CD tools, Constructor recognizes and displays additional details. For example, if you use Netlify, Constructor will display a link to the deploy preview right on the ticket's card (or a link to the build log if the build fails).
We're constantly adding additional CI/CD tools that Constructor automatically recognizes and displays. Contact us if you're using one that isn't currently recognized.

Step-by-step

Setting up the integration

To set up the GitHub integration, visit Admin Settings | Integrations and click Connect GitHub. You'll be redirected to GitHub's OAuth flow, where you can select which repositories Constructor can access and then install the Constructor app on your GitHub account.
The app can be installed on a GitHub user account or a GitHub organization account. If you have access to more than one GitHub account, take a moment to ensure you pick the right one on GitHub's OAuth screen. If you have repositories spanning multiple GitHub accounts, contact us.
The Admin Settings section is only visible to team members with the Admin role.

Linking a pull request to a ticket

To link a pull request with a ticket, just ensure the pull request's head branch name contains the ticket ID.
For example, for ticket ID #123, the branch name could use these patterns:
  • 123-foo-bar
  • 123_foo_bar
  • baz/123-foo-bar
Alternatively, visit the ticket's page and use the automatically generated suggested branch name.
Learn more about linking a pull request to a ticket:

Removing the integration

To remove the GitHub integration, visit your GitHub account's settings page, find the Constructor app from the list, and uninstall it from your account.