GitHub Actions "The deployment branch is not allowed"

When you create a deployment through the API for an environment with a branch policy, GitHub rejects the request if the ref is outside the policy. This surfaces as a 422 from the deployments API, distinct from the job-level gate.

What this error means

A script or action calling POST /repos/{owner}/{repo}/deployments returns a 422 referencing the branch policy.

github-actions

Error: Validation Failed (422)
"The deployment branch is not allowed by the environment's deployment branch policy."

Common causes

API deployment ref outside the policy

The ref passed to the deployments API does not satisfy the environment branch restriction.

Custom deployment tooling bypassing the job environment

A bespoke deployment script creates deployments directly and trips the same branch policy at the API layer.

How to fix it

Use an allowed ref or relax the policy

Pass an allowed branch as the deployment ref.
Or widen the environment deployment-branch policy to include the ref pattern.
Confirm the environment name in the API call matches the protected environment.

actions/github-script

await github.rest.repos.createDeployment({
  owner, repo,
  ref: 'main',
  environment: 'production',
  required_contexts: [],
});

How to prevent it

Keep API-driven deployments on refs that satisfy the environment branch policy.
Prefer the job-level environment key over hand-rolled deployment API calls where possible.