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

Quick start

Get started in three steps:

1. Install Flat's GitHub app: Visit Admin Settings | Integrations and click Connect GitHub to install Flat's GitHub app on your GitHub account. All of your existing and new workspaces will automatically be configured for software development and show the Code section.
2. 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.
3. 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.

Note

The Software development option is only displayed in the Workspace setup dialog after you've installed Flat's 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 requests 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.

Note

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.

Note

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 Flat's 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.

Caution

Flat's GitHub app requests only a limited set of permissions. It does not have permission to read or modify your git repository contents.

Note

The Admin Settings section is only visible to team members with the Admin role.

Configuring workspaces for software development

After installing the GitHub integration, you can choose which workspaces are used for software development.

By default after you install the integration, all of your existing and new workspaces will automatically be configured for software development. To toggle software development off for specific workspaces, or to change the default for new workspaces, see Configuring workspace options.

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 Flat's GitHub app, and uninstall it from your account.