Set job start timeout in Gitlab CI

GitLab CI (continuous integration) is a part of the GitLab platform. It allows us to define and configure pipelines as code using a YAML file called .gitlab-ci.yml within our projects' repositories. These pipelines consist of one or more stages, and each stage can contain multiple jobs.

Explore CI (continuous integration) and CD (continuous deployment) pipelines in detail.

The timeout keyword in GitLab CI

In GitLab CI, the timeout keyword defines a maximum time limit for a job to run. If the job exceeds the fixed timeout value, GitLab CI will automatically terminate the job.

Note: This Answer assumes your prior familiarity with GitLab.

We have a sample project in d3.js which displays a force-directed graph on the screen. Suppose you're managing this project on GitLab. Your file hierarchy will look as follows:

image: node:14

stages:
  - build
  - test
  - deploy

before_script:
  - npm install

build:
  stage: build
  script:
    - npm run build

test:
  stage: test
  script:
    - npm run test

deploy:
  stage: deploy
  script:
    - npm run deploy
  environment:
    name: production

You can follow the steps given below, to add a job start timeout.

  • Navigate to your .gitlab-ci.yml file.

  • Locate build, test, and deploy jobs.

  • Add timeout keyword followed by a :. Then add the duration in which you want your project to time out.

  • If the job exceeds its specified timeout, GitLab CI will automatically terminate the job and mark it failed.

image: node:14
stages:
  - build
  - test
  - deploy
before_script:
  - npm install
build:
  stage: build
  script:
    - npm run build
  timeout: 30 minutes
test:
  stage: test
  script:
    - npm run test
  timeout: 1 hour
deploy:
  stage: deploy
  script:
    - npm run deploy
  environment:
    name: production
  timeout: 2 hours

Code explanation

  • Line 1: The image keyword specifies the Docker image to use for the CI/CD pipeline. In this case, it's set to node:14, which means the pipeline will run in an environment based on Node.js version 14.

  • Lines 3–4: The stages section defines the different stages of the CI/CD pipeline. In this example, we have three stages: build, test, and deploy.

  • Lines 8–9: The before_script section allows you to specify the commands that need to be executed before running the jobs in each stage. In this case, it runs npm install, which installs the project dependencies before executing any other job in the pipeline.

  • Lines 11–15: The build job is defined in the build stage. It represents the process of building the d3.js project. The script section contains the command npm run build, which executes the build script defined in the project. Additionally, the timeout field specifies a maximum duration of 30 minutes for the job to run. If the job exceeds this time limit, it will be terminated.

  • Lines 17–21: The test job is defined in the test stage. It represents the process of running tests. The script section contains the command npm run test, which executes the test script defined in the project. The timeout field specifies a maximum duration of 1 hour for the job to run.

  • Lines 23–29: The deploy job represents the process of deploying the built d3.js project, likely to a production environment. The script section contains the command npm run deploy, which executes the deploy script. The environment field is used to define the deployment environment (set to production in this case). Lastly, the timeout field specifies a maximum duration of 2 hours for the job to run.

Conclusion

Choose an appropriate timeout duration based on the expected execution time of your job. It's worth noting that the timeout keyword is optional, and you can choose to omit it if you don't want to enforce any specific time limit on your jobs.

Free Resources

Copyright ©2026 Educative, Inc. All rights reserved