Approve and merge a GitHub PR
This page describes how a PR on a registered repository is requested and merged through an approval. Connecting GitHub and registering repositories is covered in Connect GitHub.
Request
Section titled “Request”- Open “New operation” under “Operations”, expand “Import a GitHub PR” and paste the PR URL.
- Press “Preview”. The diff, CI, precheck and rule assessment appear.
- Check the content and press “Request approval”. The approval route comes from the repository settings.
Creating the request adds the approval check Actagate / approval to the PR head in the queued state. A self-hosted App uses its own display name in the check name. The details link of the check leads back to the request.
Approve
Section titled “Approve”Approvers review the PR on the request detail and approve or reject it. When the approval completes, the check becomes “success” and the PR receives a comment with the approver and the request URL. A rejection, return or withdrawal sets the check to “failure” and comments with the reason. PRs created by people are never closed.
A push to the PR after approval is noticed when the request detail is opened and right before the merge. The approval check goes back to queued once for each new head, and the request detail shows “The PR changed after approval. Duplicate it as a draft.” The link opens the import screen with the same PR URL so you can request it again.
On repositories whose merge mode is “App merges after approval”, an operator merges from the execution console.
- Press “Open the execution console” on the request detail, then “Start”.
- Enter the PR number in the dangerous-operation confirmation and press “Run”.
Right before the merge the following conditions are checked. If any of them fails, the step fails and stops. There is no automatic retry. The reason stays on the request detail and in the execution log.
- The head SHA equals the approved one
- The PR is open and mergeable is true
- Every required check has succeeded
- The approval check has succeeded
When the merge method is “repository default”, the first allowed one of squash, merge and rebase is used. The merge commit SHA is kept as evidence.
On repositories whose merge mode is “approval check only”, the step completes when the approval completes. A person merges on GitHub. With branch protection requiring the approval check, GitHub blocks a merge before approval.
Watch the result
Section titled “Watch the result”On repositories with a watched workflow, the run for the merge commit is looked up after the merge. The lookup happens when the request detail is opened, when “Check result” is pressed on the request detail, and when “Check status” is pressed in the execution console. There is no resident monitor.
| Run state | Step state |
|---|---|
| Success | Completed. The run URL and conclusion are kept as evidence |
| Failure | Attention required. The request detail shows the tail of the job log |
| No run, or not finished, within the time limit | Result unknown, attention required |
A failed run is fixed and rerun by a person on GitHub. Record the result in the execution console.
Copy mode
Section titled “Copy mode”When the GitHub API is unavailable in the execution console, the App lacks permission, or the rate limit is hit, the step returns to copy mode. The execution console shows a command in the form gh pr merge <number> --repo <owner>/<name> --squash --match-head-commit <sha>, together with the “manual instructions” from the settings, the PR URL and the approved head SHA.
- Run the command locally so a person merges.
- Paste the merge commit SHA (40 characters) into the “Output” field of the execution console. With a watched workflow, also paste the run URL (
https://github.com/<owner>/<name>/actions/runs/<number>). - Press “Record result”. If either value is missing, nothing is recorded and the step stays ready.
When you run workflow_dispatch by hand, enter the request ID so it stays on the run. The input definition is in Connect GitHub.
Require the approval check with branch protection
Section titled “Require the approval check with branch protection”Edit the branch protection in the GitHub repository settings, enable Require status checks to pass before merging and make Actagate / approval required. “Check branch protection” in the settings screen shows whether the branch is protected and which checks are required.
On repositories where branch protection is not available, set the merge mode to “App merges after approval” and add a step at the top of the workflow that fails with if: github.actor != 'actagate[bot]'. A change pushed directly by a person stops at that job and is applied together with the next approved merge.
If GitHub is still computing mergeability, wait briefly and retry. A failed workflow read while viewing the request leaves the polling state unchanged.
The copy command follows the configured merge method. For “repository default”, it omits method flags such as --squash, and gh asks you to pick one of the methods the repository allows. The plan also displays “repository default”.