Pull request workflows
In your organization you will have a series of workflows. A workflow is a set of steps that you expect a PR to go through, including review requirements, CI results, and other rules for PR acceptance.
When a new pull request is opened, it will match the first workflow that it meets the conditions for.
When a PR matches a workflow, it will flow through the steps of the workflow until it reaches the final "Ready for merge" step.
When it reaches the final step, the PR will have a "success" status in GitHub.
Workflow conditions
Workflows belong to your entire organization, not just a specific repo.
By writing "conditions", you can decide exactly which PRs will use the workflow. This gives you the ability to define common workflows that apply to many repos, although you can also define workflows that only apply to specific repos.
In general, you'll want to define a workflow if the start-to-finish process for the pull request is different from other pull requests in your organization. For example, if you use "staging" branches for testing, you may want developers to freely open and merge PRs as opposed to "main" where you need to get approvals and run through a series of other checks.
Examples:
- Staging branches:
pull.base.ref == "staging" - Specific repos:
pull.repo == "org/repo"orpull.repo.name.startswith("terraform-") - Dependency update PRs:
pull.author == "dependabot[bot]" - Public vs private contributions:
pull.repo.private == False
When to use workflow conditions vs team conditions
Workflows and review teams both have "conditions". The rule of thumb is, if the entire process for a pull request is different, then you should use a workflow condition. But if the process is the same and the only difference is who reviews the PR, then you use one workflow and multiple teams with their own conditions.Workflow steps
Within a workflow there are "steps".
When a PR matches a workflow, it will then move through the steps in order, only moving to the next step when it satisfies the requirements for the previous steps.
Each step has requirements and notifications. Visually it gives people a way to see "where the PR is at" and what's required for the PR to keep moving forward. Notifications can be used to automatically provide next steps for reviewers and contributors. The current step is also shown in the GitHub status check.
Step requirements
These are rules that must be met for a pull request to move on to the next step. Because steps are evaluated in order, you can think of the step requirements as a series of "gates" or "checks" that a pull request must pass to receive a successful status in GitHub.
Requirements are written as expressions that have direct access to the GitHub API. So, in addition to requiring your review teams to approve a pull request, you can also set up "pre-requisites" that need to met before a review takes place, or "post-requisites" that need to be met after review but before a pull request can be merged.
Examples of requirements:
- Team approval:
teams.all_approvedorteam["Team name"].approved - GitHub checks status:
"test" in pull.check_runs.succeeded - Requiring PR labels:
len(pull.labels) > 0 - Requiring specific files to be changed:
"file.txt" in pull.files - Preventing specific files from being changed:
"file.txt" not in pull.files
Step notifications
To keep people in the loop about the status of a pull request, you can configure GitHub comments to be sent when a PR either enters or exits a specific step.
This is often used to provide concrete next steps for reviewers and contributors.
Notifications are rendered using templates.
Unmatched status
It's possible for a pull request to not match any workflow. This all depends on what your last workflow's conditions are – if you leave them empty, then any pull requests that don't match any other workflow will match the last workflow. But if you have specific conditions on the last workflow, then any PRs without a workflow will use the "unmatched status" to report back to GitHub.
You can configure the unmatched status in your organization settings. By default it will be "(None)" which means no PullApprove status will appear on GitHub if the PR doesn't match a workflow. You can configured this to be pending/error/failure if you want to enforce that all PRs must match a workflow, or "success" if PullApprove is a required status check and you want unmatched PRs to be able to merge.
