GitHub
Overview
If you're using Flat with a software team, Flat'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 in the workspace on their associated topic's card
Making it easy to jump between the topic in Flat 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
Quick start
Get started in three steps:
Install the Flat GitHub app: Visit Admin Settings | Integrations and click Connect GitHub to install the Flat GitHub app on your GitHub account.
Link a pull request to a topic: Visit a topic's page, scroll down to the Code section, and copy the suggested branch name. Any pull requests using that branch name will get linked to the topic. You can also use custom branch names; see Code.
Optionally, show topic IDs: Visit Personal Settings | Appearance and enable Show topic IDs to always show a topic's ID next to its title. The suggested branch name incorporates the topic ID regardless of whether you enable this setting. However, developers usually prefer to see explicit topic IDs for extra clarity and easier reference.
The Code section is only displayed on topics after you've installed the Flat GitHub app.
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 request's to topics based on the head branch name. After you've enabled the integration, Flat gives every topic's page a Code section with a suggested branch name. You can also use your own branch names as long as they follow a simple pattern (see Code).
Many-to-one-model
You can link as many pull requests as you like to the same topic.
Some teams prefer a model where a topic can have only one pull request. If the developer needs to make additional code changes, they make a new topic first.
However, that can easily lead to an overwhelming number of topics, increasing clutter and hindering collaboration. We recommend using multiple pull requests per topic.
Automatic CI/CD detection
If your team has connected a CI/CD tool to your GitHub repository for code quality checks, testing, builds, etc., Flat will automatically detect it and display the live build status right on the topic's card.
For many common CI/CD tools, Flat recognizes and displays additional details. For example, if you use Netlify, Flat will display a link to the deploy preview right on the topic's card, or a link to the build log if the build fails.
We're constantly adding additional CI/CD tools that Flat 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 Flat can access and then install the Flat 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 topic
See Code.
Removing the integration
To remove the GitHub integration, visit your GitHub account's settings page, find the Flat app from the list, and uninstall it from your account.
Last updated