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.

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