The timeout keyword in a GitLab CI/CD job definition allows you to specify a maximum execution time for that job. If the job runs longer than the specified duration, GitLab CI will automatically cancel (and fail) the job. This is crucial for preventing stuck jobs from consuming runner resources indefinitely.

Example .gitlab-ci.yml with timeout:

This example includes two jobs: one that will likely exceed its timeout and another that should complete within its timeout.

YAML

# .gitlab-ci.yml

stages:
  - process
  - quick_task

default:
  image: alpine:latest

# Job 1: This job is designed to exceed its specified timeout
long_running_job_with_timeout:
  stage: process
  timeout: 30 seconds # Set a timeout of 30 seconds for this job
  script:
    - echo "--- Long Running Job with Timeout ---"
    - echo "This job has a 30-second timeout."
    - echo "Starting a task that will take 45 seconds..."
    - sleep 45 # This command will cause the job to exceed its 30s timeout
    - echo "This line will likely NOT be reached because the job will time out."
  after_script: # after_script also has its own timeout, separate from the job's main script timeout
    - echo "After_script: This runs even if the main script timed out or failed."
    - echo "Job status at this point: $CI_JOB_STATUS"

# Job 2: This job should complete within its timeout
quick_job_with_timeout:
  stage: quick_task
  timeout: 1 minute # Set a timeout of 1 minute for this job
  script:
    - echo "--- Quick Job with Timeout ---"
    - echo "This job has a 1-minute timeout and should complete successfully."
    - echo "Performing a quick task..."
    - sleep 10 # This task takes only 10 seconds
    - echo "Quick task finished well within the timeout."
  after_script:
    - echo "After_script: Quick job finished. Status: $CI_JOB_STATUS"

Code language: PHP (php)

Explanation:

1. timeout: Keyword:
   • Used within a job definition to specify the maximum allowed execution time for that job’s script section.
   • If the job’s script execution time exceeds this value, GitLab CI will stop the job, and it will be marked as failed with a “job execution timeout” reason.
2. long_running_job_with_timeout Job:
   • timeout: 30 seconds:
     • This job is configured to time out after 30 seconds.
   • script::
     • sleep 45: This command will pause execution for 45 seconds. Since this is longer than the 30-second timeout, this job is expected to be terminated by GitLab CI before the sleep command completes.
     • The final echo statement in the script will likely not be executed.
   • after_script::
     • Commands in after_script are executed after the main script finishes, regardless of whether the main script succeeded, failed, or timed out.
     • after_script has its own, separate timeout (usually shorter, configured by the GitLab administrator at the instance or runner level). It does not inherit the job’s timeout.
     • The $CI_JOB_STATUS variable within the after_script will reflect the status of the main script (e.g., failed if it timed out).
3. quick_job_with_timeout Job:
   • timeout: 1 minute: This job has a more generous timeout of 1 minute.
   • script::
     • sleep 10: This command only pauses for 10 seconds, which is well within the 1-minute timeout.
     • This job should complete successfully.

Duration Format:

The timeout value is specified as a human-readable duration. GitLab supports various units and combinations:

• s or second or seconds
• m or minute or minutes
• h or hour or hours
• Examples:
  • timeout: 5s (5 seconds)
  • timeout: 10m (10 minutes)
  • timeout: 1h 30m (1 hour and 30 minutes)
  • timeout: 2 hours
  • timeout: 300 (Interpreted as 300 seconds, but using units is clearer)

Key Concepts and Behavior:

• Purpose: To prevent runaway jobs from consuming excessive CI/CD runner time and resources. It acts as a safeguard.
• Job Failure: When a job times out, it’s marked as failed in the pipeline, and the failure reason will indicate a timeout.
• Scope:
  • Job-level timeout: As shown in the example, defined per job.
  • Project-level default timeout: You can set a default timeout for all jobs in your project under Settings > CI/CD > General pipelines > Timeout. Job-level timeouts will override this project default.
  • Runner-level timeout: GitLab Runner configurations might also have maximum timeout settings. The most restrictive timeout (job, project, or runner) will apply. For example, if a job specifies timeout: 2 hours but the runner is configured with a maximum of 1 hour, the job will time out after 1 hour.
• after_script Timeout: As mentioned, after_script has its own independent timeout, which is generally not configurable via the .gitlab-ci.yml job timeout keyword but at the runner or instance level.
• Use Cases:
  • Preventing stuck deployment scripts.
  • Limiting the time for long-running test suites that might have performance regressions.
  • Ensuring resource-intensive jobs don’t block runners for too long.
  • Setting realistic expectations for how long a particular automated task should take.

Setting appropriate timeouts is an important part of maintaining a healthy and efficient CI/CD pipeline. It helps in quickly identifying and addressing jobs that are taking longer than expected.