Use Job Timeout

In this guide, you’ll learn how to set a job-level timeout in GitLab CI/CD. Long-running or stalled jobs—caused by script errors, network issues, or unresolved dependencies—can block pipelines and consume resources. By defining a timeout, any job that exceeds the allotted time is automatically terminated.

Sample Pipeline Without Timeout

Here’s a basic pipeline that deploys an application but uses a sleep command to simulate a long-running step:

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  variables:
    DEPLOY_VARIABLE: PRODUCTION

deploy-job:
  resource_group: production
  script:
    - echo "Deploying application..."
    - sleep 30s
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

Why Use Job-Level Timeouts?

• Prevent rogue or hung jobs from consuming runner resources
• Ensure faster pipeline feedback and fail-fast behavior
• Avoid billing surprises on shared or cloud runners

Adding a Timeout to a Job

To configure a timeout, add the timeout keyword to any job. GitLab supports human-readable durations in a variety of formats:

build:
  script: ./build.sh
  timeout: 3 hours 30 minutes

test:
  script: rspec
  timeout: 3h 30m

lint:
  script: ./lint.sh
  timeout: 3600 seconds

Supported Duration Formats

For more details, see GitLab CI/CD Timeout Settings.

Example: Forcing a Fast Failure

If you want your deploy-job to be canceled after 10 seconds, add timeout: 10s:

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  variables:
    DEPLOY_VARIABLE: PRODUCTION

deploy-job:
  resource_group: production
  timeout: 10s
  script:
    - echo "Deploying application..."
    - sleep 300s
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

When the job exceeds 10 seconds, the runner will terminate it and you’ll see:

ERROR: Job failed: execution took longer than 10 seconds

Final Pipeline Configuration

Below is the complete pipeline configured with a 10-second timeout for deploy-job:

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  variables:
    DEPLOY_VARIABLE: PRODUCTION

deploy-job:
  resource_group: production
  timeout: 10s
  script:
    - echo "Deploying application..."
    - sleep 360s
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

Choose a timeout value that aligns with your job’s expected duration to maintain pipeline reliability and resource efficiency.

Links and References

• GitLab CI/CD Pipeline Configuration
• Job Timeout Settings
• GitLab Runner Executors