How to Set a Job Timeout in GitLab CI

By Kaveh Alemi·Latchkey

GitLab caps a job with the timeout keyword using a human-readable duration like 30m or 1h 30m.

Set timeout: on a job to bound its runtime. It must be below the runner timeout, which itself overrides the project-level default.

Per-job timeout

This job is killed if it runs longer than 30 minutes, regardless of the project default.

.gitlab-ci.yml

test:
  timeout: 30m
  script:
    - npm ci
    - npm test

e2e:
  timeout: 1h 30m
  script:
    - npm run test:e2e

Gotchas

The effective limit is the smallest of job timeout, runner timeout, and project timeout - a job timeout larger than the runner timeout is ignored.
Durations are human-readable (30m, 1h, 3h 30m), not seconds.
A timed-out job fails; use it as a safety net so a hung job does not occupy a runner indefinitely.

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 set a Job Timeout in GitLab CI?

Set timeout: on a job to bound its runtime. It must be below the runner timeout, which itself overrides the project-level default.

Per-job timeout?