How to run a manual job in GitLab CI/CD, and why the pipeline is blocked

A manual job is a CI/CD job that waits for a person to start it, the usual way to gate a production deploy. If your pipeline says blocked, or a job shows a play button instead of running, this is why. Here is how manual jobs work in GitLab in 2026, how to run one, and how to control who can.

Make a job manual

Add when: manual to the job in .gitlab-ci.yml:

deploy_prod:
  stage: deploy
  script:
    - ./deploy.sh production
  environment: production
  when: manual

When the pipeline starts, a manual job shows as skipped until someone runs it.

Optional or blocking

Where you put when: manual decides whether the rest of the pipeline waits:

	Optional manual job	Blocking manual job
allow_failure	true, the default for when: manual outside rules	false, the default for when: manual inside rules
The pipeline	Carries on; the job doesn’t affect its status, and it can succeed even if the job fails	Stops at that job’s stage and shows blocked
The merge request	Unaffected	Can’t merge while blocked, if the project requires pipelines to succeed

So if a pipeline is stuck on blocked, there’s a manual job waiting to be run: when: manual inside rules without allow_failure: true, or any manual job with allow_failure: false. Run it, and once it succeeds the later stages continue.

Run it

Open the pipeline, job, environment or deployment view, and select Run next to the manual job. You need permission to merge to the branch the job runs for.

From a terminal or a script:

• GitLab CLI: glab ci trigger deploy_prod runs a manual job by name, or pass its ID; without an argument it lets you pick one. --branch and --pipeline-id choose where to look.
• API: POST /projects/:id/jobs/:job_id/play, with optional job_variables_attributes or job_inputs.

Run it with variables

To change how the job behaves this once, select the job’s name in the pipeline view instead of Run, add key and value pairs, and select Run job. A value you enter overrides any variable of the same name from the project settings or .gitlab-ci.yml.

Treat those values as visible. They are expanded and not masked, and project members who can run the job can retry it and see what you entered. In private and internal projects, that includes every role from Guest up. When you retry a manual job that ran with variables, you can keep or change them. For typed, validated parameters, GitLab recommends job inputs instead.

Ask for confirmation first

Since GitLab 17.1, manual_confirmation adds a confirmation message that must be accepted before the job runs. It’s useful for deploys and deletes; environment stop jobs like this one need GitLab 18.3 or later:

stop_production:
  stage: deploy
  script:
    - ./teardown.sh
  environment:
    name: production
    action: stop
  when: manual
  manual_confirmation: "Are you sure you want to stop production?"

Limit who can run it

By default, anyone who can merge to the branch can run the job. On Premium and Ultimate, give the job an environment and make it a protected environment. Then only the users, roles or groups in its Allowed to deploy list, plus administrators, can run it. Combine that with allow_failure: false and the manual job becomes an approval gate: later stages run only after an authorized person starts it.

Running deploys from your phone

A manual deploy waiting on you is a good reason to reach for your phone. In MergeBell, a pipeline shows its jobs with live logs, and you can play a manual job, retry a failed one or cancel a stuck one, all on the free tier. It runs with your own GitLab token, so GitLab’s permission checks and protected environments still apply. More on fixing pipelines from anywhere in how to retry a failed GitLab pipeline.