How to Trigger a GitLab CI Pipeline Manually

By Daniel Zoghalchali·Latchkey

GitLab gates jobs behind a play button with when: manual, turning any job into an on-demand action.

Set when: manual on a job so it waits for a click. Use the Run pipeline form (Pipelines > Run pipeline) to launch a pipeline with custom variables.

Manual gate before deploy

The deploy job will not run until someone clicks play; allow_failure: false makes it block the pipeline.

.gitlab-ci.yml

deploy:prod:
  stage: deploy
  when: manual
  allow_failure: false
  environment: production
  script:
    - ./deploy.sh production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Gotchas

By default a manual job is allow_failure: true (optional). Set it to false to make it a true blocking gate.
With rules:, combine when: manual inside a rule rather than at the top level for conditional manual jobs.
Protected environments restrict who can click play - use them for production gates.

Verify it actually works

Terminal

# validate the pipeline definition against your project's CI lint
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# then confirm which rules matched on a real pipeline
# CI/CD -> Pipelines -> the run -> each job -> "Trigger"

Frequently asked questions

How do I trigger a GitLab CI Pipeline Manually?

Set when: manual on a job so it waits for a click. Use the Run pipeline form (Pipelines > Run pipeline) to launch a pipeline with custom variables.

Manual gate before deploy?

The deploy job will not run until someone clicks play; allow_failure: false makes it block the pipeline.

References

GitHub Actions documentation