GitHub Actions waiting for approval to run workflows for this PR
GitHub Actions waiting for approval to run workflows means a maintainer has to release the run before any job is created. Nothing has failed, nothing is queued on a runner, and the checks that are required to merge cannot report until somebody clicks.
What this error means
A pull request from a contributor shows no progress at all. There is no red check and no running job, just a note that a workflow is awaiting approval, and the merge box reports that required checks have not completed. From the contributor's side it looks like the automation is broken; from the maintainer's side it is easy to miss, because nothing failed and nothing sent a failure notification.
1 workflow awaiting approval
This workflow requires approval from a maintainer.Nothing is wrong, and that is the difficulty
This is not an error and it does not appear in any log, because there is no log. The Actions service holds the event, decides that a person has to authorize it, and stops there. No run is scheduled, no job is created, no runner is assigned and no step exists to inspect. Everything you can learn about it is in the pull request page rather than in the Actions tab.
That is also why it blocks merging so effectively. Required status checks are satisfied by checks reporting success, and a check that was never dispatched reports nothing at all. The pull request is not failing its requirements; it is failing to have results, which the merge box presents in much the same way.
Common causes
The contributor has not had a pull request merged here before
The common configuration. First-time contributors are held and everyone else is not, which is why the situation appears sporadically and usually to the people least able to interpret it.
The policy applies to all fork pull requests
A stricter setting holds every outside contribution regardless of history. Repositories that receive occasional drive-by contributions can sit under this without anyone noticing, because the maintainers never trigger it themselves.
An organization or enterprise policy is stricter than the repository
The repository settings look permissive and runs are still held, because a higher level is deciding. In our experience this is the version that consumes the most time, since the repository page appears to contradict the behavior.
The pull request was opened by an automation account treated as an outside contributor
Worth ruling out when a bot's pull requests stall. An account without prior merged contributions is subject to the same rule, so a newly introduced automation can start needing approval on every run it opens.
How to fix it
Approve the run from the pull request
- Open the pull request and read the changed files, including any change to a workflow file.
- Click the Awaiting approval button at the top right to open the Merge status panel.
- Click Approve workflows to run.
- Expect to repeat this for later pushes until the contributor has a merged pull request here.
Decide the policy deliberately rather than inheriting it
Review the setting at the repository level and check whether the organization or enterprise is imposing something stricter. A project that wants drive-by contributions and a project that runs expensive jobs on every push want different answers, and the default is not tuned for either.
Make the contributor-facing checks need no approval to be useful
If the valuable signal is lint and unit tests, consider whether those need secrets or write access at all. Work that runs safely without either is the work that argues best for a looser approval policy.
Watch the 30 day limit on long-lived pull requests
A pull request that stalls in review can lose its pending run entirely. If a run has disappeared rather than completed, push a commit or close and reopen the pull request to produce a fresh event, then approve that.
What the maintainer actually does
The approval is two clicks and it is in a place people do not look, which is most of why these sit for days. GitHub documents the sequence: open the pull request, go to the changed files and read them, and then, in its words, "click the button in the upper right corner labeled Awaiting approval, which will open the Merge status panel", and "Find and click Approve workflows to run".
The instruction to read the changes first is not decoration. Approving dispatches the contributor's workflow file and the contributor's code onto a runner holding your repository's token, so the review is the control the policy exists to create.
Which contributors are held, and for how long
The policy is configurable at three levels and the choice decides how often anyone has to do this.
| Where the policy is set | What it controls | Practical effect |
|---|---|---|
| Repository settings | Which fork contributors need approval here | The usual place to loosen or tighten it for one project |
| Organization settings | A default across the organization's repositories | Where a policy that surprises a single repository usually comes from |
| Enterprise settings | Fork pull request workflows from outside collaborators | Can hold the others off entirely |
Why there is no recorded run on this page
The subject of this page is a run that does not exist. There is nothing to record because nothing was dispatched: no machine picked the work up, no step executed, and the only artifact is a sentence in the pull request's merge box, which is quoted above from a public issue. A recorded run would necessarily be a run that had already been approved, which is the state this page is about not being in.
How to prevent it
- Subscribe the people who triage contributions to the pull requests that will hold, since nothing sends a failure notification.
- Say in the contributing guide that a maintainer has to release the first run, so a contributor does not read silence as breakage.
- Check the organization and enterprise settings before concluding the repository is misconfigured.
- Keep the checks required for merge to ones that can run without approval wherever that is possible.