GitHub
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
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.
The GitHub integration works by automatically linking pull requests to topics using the pull request's head branch name.
For example, a pull request using branch names similar to these would be linked to topic
#123:123123-foo-bar123_foo_barbaz/123-foo-bar
Flat doesn't support linking code to topics if you push commits directly to your trunk branch. You must first push the commits to a separate branch with a name containing the topic's ID, then open a pull request from that branch to your trunk branch.
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.
Feel free to use that model if you prefer. However, it can easily lead to an overwhelming number of topics that obscures your team's work and hinders collaboration. Instead, we recommend being less rigid and using multiple pull requests per topic.
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.
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.
To link a pull request with a topic, just ensure the pull request's head branch name contains the topic ID.
For example, for topic ID
#123, the branch name could use these patterns:123123-foo-bar123_foo_barbaz/123-foo-bar
Alternatively, visit the topic's page and use the automatically generated suggested branch name.
Learn more about linking a pull request to a topic:
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 modified 1mo ago