Explore GitHub flow

  • 3 minutes

GitHub is the best tool to enable collaboration in your projects. GitHub flow is a branch-based workflow suggested for GitHub.

Note

To implement GitHub flow, you'll need a GitHub account and a repository. See "Signing up for GitHub" and "Create a repo."

Tip

You can complete all steps of GitHub flow through the GitHub web interface, command line, GitHub CLI, or GitHub Desktop.

The first step is to create a branch in your repository to work without affecting the default branch, and you give collaborators a chance to review your work.

For more information, see "Creating and deleting branches within your repository."

Screenshot of a branching model representing the branch creation.

Make any desired changes to the repository. If you make a mistake, you can revert or push extra changes to fix it.

Commit and push your changes to your branch to back up your work to remote storage, giving each commit a descriptive message. Each commit should contain an isolated, complete change making it easy to revert if you take a different approach.

Anyone collaborating with your project can see your work, answer questions, and make suggestions or contributions. Continue to create, commit, and push changes to your branch until you're ready to ask for feedback.

Tip

You can make a separate branch for each change to make it easy for reviewers to give feedback or for you to understand the differences.

Once you're ready, you can create a pull request to ask collaborators for feedback on your changes. See "Creating a pull request."

Pull request review is one of the most valuable features of collaboration. You can require approval from your peers and team before merging changes. Also, you can mark it as a draft in case you want early feedback or advice before you complete your changes.

Screenshot of a branching model representing an open a pull request.

Describe the pull request as much as possible with the suggested changes and what problem you're resolving. You can add images, links, related issues, or any information to document your change and help reviewers understand the PR without opening each file. See "Basic writing and formatting syntax" and "Linking a pull request to an issue."

Screenshot of open a pull request representation with description field, related issue and a checklist template.

Another way to improve PR quality and documentation and explicitly point something out to the reviewers is to use the comment session area. Also, you can @mention or request a review from specific people or teams.

Screenshot of pull request comment field.

There are other Pull Requests configurations, such as automatically requesting a review from specific teams or users when a pull request is created or checks to run on pull requests. For more information, see "About status checks" and "About protected branches."

After the reviewers' comments and checks validation, the changes should be ready to be merged, and they can approve the Pull Request. See Merging a pull request."

If you have any conflicts, GitHub will inform you to resolve them. "Addressing merge conflicts."

Screenshot of a branching model representing the branch merge.

After a successful pull request merges, there's no need for the remote branch to stay there. You can delete your branch to prevent others from accidentally using old branches. For more information, see "Deleting and restoring branches in a pull request."

Note

GitHub keeps the commit and merges history if you need to restore or revert your pull request.