GitLab CI "This manual job ... cannot be run" in CI

A when: manual job cannot be started: its stage was skipped, a job it needs has not succeeded, or your role lacks permission to play it. Manual jobs are only playable once their prerequisites are met.

What this error means

The play button is disabled or clicking it returns "This job cannot be run" / "Playing the job is not allowed". The job stays in a manual or skipped state.

Job page

This job cannot be run because it does not have all the required prerequisites.

Common causes

A prerequisite job has not succeeded

If the manual job needs an earlier job that failed or did not run, it cannot be played.

Insufficient permission to run the job

Running a protected or deployment manual job requires a role with permission for that environment or branch.

How to fix it

Satisfy the prerequisites

Confirm every job the manual job needs has succeeded.
Re-run any failed upstream jobs first.
Then play the manual job.

.gitlab-ci.yml

deploy:
  stage: deploy
  when: manual
  needs: ["build"]
  script: ./deploy.sh

Check protected environment permissions

For deployments to protected environments, ensure your role is allowed to deploy, or have a maintainer run it.

How to prevent it

Keep manual jobs' needs chain green before expecting to play them.
Grant the right roles access to protected environments.
Document who can run manual deployment jobs.