Pull request workflows

Organize your pull requests into distinct worfklows.

A workflow is a series of steps that a PR goes through. You can think of these as "gates", where each step has its own requirements. Requirements can be any combination of human approval requirements or automated checks on the state of the PR (e.g. CI tests passing, description filled out, issues linked).

A basic example of steps in a workflow might be:

• Pre-review - hold any "draft" PRs here
• Tests required - require all CI tests to pass before review
• In review - require at least one approval from the relevant teams
• Ready for merge

As a PR moves through the workflow, the current status is reflected in GitHub.

The status will be "pending" until it reaches the final step of a workflow, at which point it will change to "success". The last step is typically called "Ready for merge".

Learn more about workflow steps →

Multiple workflows

Most likely, your organization will have multiple workflows to "bucket" PRs that have similar review processes.

Contrary to what you might expect, workflows are defined at the organization level, not at the repository level. This makes it possible to share workflows across an organization, while still giving you the control to write per-repo workflows using conditions.

Multiple workflows can be used to group PRs by:

• Repository name, topics, or language
• Public vs private repositories
• Branch naming patterns (e.g. release/*)
• Automated vs human contributions (e.g. dependabot)
• PR size
• More via expressions

When a new pull request is opened, it will match the first workflow that it meets the conditions for.

Learn more about workflow conditions →