doc/ci/jobs/_index.md
{{< details >}}
{{< /details >}}
CI/CD jobs are the fundamental elements of a GitLab CI/CD pipeline.
Jobs are configured in the .gitlab-ci.yml file with a list of commands to execute
to accomplish tasks like building, testing, or deploying code.
Jobs:
Jobs are defined with YAML keywords that define all aspects of the job's execution, including keywords that:
To add a job to a pipeline, add it into your .gitlab-ci.yml file. The job must:
script section defining commands to run,
or a trigger section to trigger a downstream pipeline
to run.For example:
my-ruby-job:
script:
- bundle install
- bundle exec my_ruby_command
my-shell-script-job:
script:
- my_shell_script.sh
You can't use these keywords as job names:
imageservicesstagesbefore_scriptafter_scriptvariablescacheincludepages:deploy configured for a deploy stageAdditionally, these names are valid when quoted, but are not recommended as they can make pipeline configuration unclear:
"true":"false":"nil":Job names must be 255 characters or fewer.
Use unique names for your jobs. If multiple jobs have the same name in a file, only one is added to the pipeline, and it's difficult to predict which one is chosen. If the same job name is used in one or more included files, parameters are merged.
To temporarily disable a job without deleting it from the configuration
file, add a period (.) to the start of the job name. Hidden jobs do not need to contain
the script or trigger keywords, but must contain valid YAML configuration.
For example:
.hidden_job:
script:
- run test
Hidden jobs are not processed by GitLab CI/CD, but they can be used as templates for reusable configuration with:
extends keyword.You can use the default keyword to set default job keywords and values, which are
used by default by all jobs in a pipeline.
For example:
default:
image: 'ruby:2.4'
before_script:
- echo Hello World
rspec-job:
script: bundle exec rspec
When the pipeline runs, the job uses the default keywords:
rspec-job:
image: 'ruby:2.4'
before_script:
- echo Hello World
script: bundle exec rspec
You can control the inheritance of:
For example:
default:
image: 'ruby:2.4'
before_script:
- echo Hello World
variables:
DOMAIN: example.com
WEBHOOK_URL: https://my-webhook.example.com
rubocop:
inherit:
default: false
variables: false
script: bundle exec rubocop
rspec:
inherit:
default: [image]
variables: [WEBHOOK_URL]
script: bundle exec rspec
capybara:
inherit:
variables: false
script: bundle exec capybara
karma:
inherit:
default: true
variables: [DOMAIN]
script: karma
In this example:
rubocop:
rspec:
image and the WEBHOOK_URL variable.before_script and the DOMAIN variable.capybara:
before_script and image.DOMAIN and WEBHOOK_URL variables.karma:
image and before_script, and the DOMAIN variable.WEBHOOK_URL variable.When you access a pipeline, you can see the related jobs for that pipeline.
The order of jobs in a pipeline depends on the type of pipeline graph.
Selecting an individual job shows you its job log, and allows you to:
{{< details >}}
{{< /details >}}
{{< history >}}
populate_and_use_build_names_table for the API and fe_search_build_by_name for the UI. Disabled by default.populate_and_use_build_names_table and fe_search_build_by_name removed.{{< /history >}}
To view jobs that ran in a project:
You can filter the list by job status, source, name, and kind.
[!note] The filter by name returns jobs created in the last 30 days. This retention period applies to both UI and API filtering.
By default, the filter shows only build jobs. To view trigger jobs, clear the filter, then select Kind > Trigger.
[!note] The Kind filter is available only for project jobs. It is not available in the Admin area.
CI/CD jobs can have the following statuses:
canceled: Job was manually canceled or automatically aborted.canceling: Job is being canceled but after_script is running.created: Job has been created but not yet processed.failed: Job execution failed.manual: Job requires manual action to start.pending: Job is in the queue waiting for a runner.preparing: Runner is preparing the execution environment.running: Job is executing on a runner.scheduled: Job has been scheduled but execution hasn't started.skipped: Job was skipped due to conditions or dependencies.success: Job completed successfully.waiting_for_callback: Job is waiting for a callback from an external service.waiting_for_resource: Job is waiting for resources to become available.{{< history >}}
populate_and_use_build_source_table. Enabled by default.{{< /history >}}
GitLab CI/CD jobs now include a source attribute that indicates the action that initially triggered a CI/CD job. Use this attribute to track how a job was initiated or filter job runs based on the specific sources.
The source attribute can have the following values:
api: Job initiated by a REST call to the Jobs API.chat: Job initiated by a chat command using GitLab ChatOps.container_registry_push: Job initiated by container registry push.duo_workflow: Job initiated by GitLab Duo Agent Platform.external: Job initiated by an event in an external repository integrated with GitLab. This does not include pull request events.external_pull_request_event: Job initiated by a pull request event in an external repository.merge_request_event: Job initiated by a merge request event.ondemand_dast_scan: Job initiated by an on-demand DAST scan.ondemand_dast_validation: Job initiated by an on-demand DAST validation.parent_pipeline: Job initiated by a parent pipelinepipeline: Job initiated by a user manually running a pipeline.pipeline_execution_policy: Job initiated by a triggered pipeline execution policy.pipeline_execution_policy_schedule: Job initiated by a scheduled pipeline execution policy.push: Job initiated by a code push.scan_execution_policy: Job initiated by a scan execution policy.schedule: Job initiated by a scheduled pipeline.security_orchestration_policy: Job initiated by a scheduled scan execution policy.trigger: Job initiated by another job or pipeline.unknown: Job initiated by an unknown source.web: Job initiated by a user from the GitLab UI.webide: Job initiated by a user from the Web IDE.If you have many similar jobs, your pipeline graph becomes long and hard to read.
You can automatically group similar jobs together. If the job names are formatted in a certain way, they are collapsed into a single group in regular pipeline graphs (not the mini graphs).
You can recognize when a pipeline has grouped jobs if you see a number next to a job name instead of the retry or cancel buttons. The number indicates the amount of grouped jobs. Hovering over them shows you if all jobs have passed or any has failed. Select to expand them.
To create a group of jobs, in the .gitlab-ci.yml file,
separate each job name with a number and one of the following:
/ or \), for example, slash-test 1/3,
slash-test 2/3, slash-test 3/3.:), for example, colon-test 1:3, colon-test 2:3, colon-test 3:3.space-test 0 3, space-test 1 3, space-test 2 3.You can use these symbols interchangeably.
In the following example, these three jobs are in a group named build ruby:
build ruby 1/3:
stage: build
script:
- echo "ruby1"
build ruby 2/3:
stage: build
script:
- echo "ruby2"
build ruby 3/3:
stage: build
script:
- echo "ruby3"
The pipeline graph displays a group named build ruby with three jobs.
The jobs are ordered by comparing the numbers from left to right. You usually want the first number to be the index and the second number to be the total.
You can retry a job after it completes, regardless of its final state (failed, success, or canceled).
When you retry a job:
When you retry a trigger job that triggers a downstream pipeline:
Prerequisites:
To retry a job from a merge request:
To retry a job from the job log:
To retry a job from a pipeline:
If a pipeline has multiple failed or canceled jobs, you can retry all of them at once:
You can cancel a CI/CD job that hasn't completed yet.
When you cancel a job, what happens next depends on its state and the GitLab Runner version:
canceling.before_script or script are skipped.after_script section, it always starts and runs to completion.canceled.canceled immediately without running after_script.If you need to cancel a job immediately without waiting for the after_script, use force cancel.
Prerequisites:
To cancel a job from a merge request:
To cancel a job from the job log:
To cancel a job from a pipeline:
You can cancel all jobs in a running pipeline at once.
{{< history >}}
force_cancel_build. Disabled by default.force_cancel_build removed.{{< /history >}}
If you don't want to wait for after_script to finish or a job is unresponsive, you can force cancel it.
Force cancel immediately moves a job from the canceling state to canceled.
When you force cancel a job, the job token is immediately revoked.
If the runner is still executing the job, it loses access to GitLab.
The runner aborts the job without waiting for after_script to complete.
Prerequisites:
canceling state, which requires:
To force cancel a job:
When a pipeline fails or is allowed to fail, there are several places where you can find the reason:
In each place, if you hover over the failed job you can see the reason it failed.
You can also see the reason it failed on the Job detail page.
You can use GitLab Duo Root Cause Analysis in GitLab Duo Chat to troubleshoot failed CI/CD jobs.
Deployment jobs are CI/CD jobs that use environments.
A deployment job is any job that uses the environment keyword and the start environment action.
Deployment jobs do not need to be in the deploy stage. The following deploy me
job is an example of a deployment job. action: start is the default behavior and
is defined here for clarity, but you can omit it:
deploy me:
script:
- deploy-to-cats.sh
environment:
name: production
url: https://cats.example.com
action: start
The behavior of deployment jobs can be controlled with deployment safety settings like preventing outdated deployment jobs and ensuring only one deployment job runs at a time.