GitHub Actions "The deployment branch is not allowed"

By Daniel Zoghalchali·Latchkey

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.

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

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

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.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions