Defining Jobs and Scripts

1. Creating Basic Job Definition

Property	Description	Example
job_name	Name of the job (must be unique within a pipeline)	`build`
script	Array of commands to run in the job	`script: - echo "Building..." - npm run build`
image	Docker image to use for the job environment	`node:18`
tags	Runner tags to select a specific runner	`["linux", "docker"]`
environment	Name of the environment to deploy to	`production`

Example: Basic job definition

build_job:
  script:
    - echo "Building the project"
    - npm install
    - npm run build
  image: node:18
  tags:
    - linux
    - docker

2. Assigning Jobs to Stages

Property	Description	Values
stage	Name of the stage this job belongs to	`build`, `test`, `deploy`, or custom stage name
needs	Jobs this job depends on in other stages	List of job names or `["*"]` for all jobs in previous stages

Example: Defining Jobs in Stages

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Building..."
    
test_job:
  stage: test
  needs: [build_job]
  script:
    - echo "Testing..."

deploy_job:
  stage: deploy
  needs: [test_job]
  script:
    - echo "Deploying..."

3. Defining Job Scripts

Property	Description	Values
script	Defines the command or script to run in the job	`string` or `array` of strings
before_script	Runs before the job's script, shared across all jobs in a pipeline	`array` of strings
after_script	Runs after the job's script, shared across all jobs in a pipeline	`array` of strings

Example: Basic script usage

job_name:
  script:
    - echo "Hello, World!"
    - npm test

Example: Using before_script and after_script

job_name:
  before_script:
    - echo "Setting up environment"
    - npm install
  script:
    - npm test
  after_script:
    - echo "Cleaning up"

Note: The script property is required for a job to run. If not defined, the job will fail.

4. Using before_script Hook

The before_script hook in GitLab CI/CD allows you to define a set of commands that run before each job's script. These commands are executed in the same environment as the job's script, ensuring that any setup or initialization steps required for the job are completed.

Property	Description	Values
before_script	Defines a list of commands to run before each job's script	`script` or `array of commands`

Example: before_script with multiple commands

before_script:
  - echo "Starting job preparation"
  - mkdir -p build
  - npm install

Note: The before_script runs in the same environment as the job's script, so any environment variables or dependencies set here will be available to the job's script.

5. Using after_script Hook

Property	Description	Values
after_script	Defines a list of commands to run after each job's script section completes, regardless of success or failure.	`script` (array of strings)

Example: after_script with cleanup

job_name:
  script:
    - echo "Running job"
  after_script:
    - rm -rf /tmp/cache
    - echo "Cleanup completed"

Note: The after_script runs even if the job fails or is canceled.

Warning: If after_script fails, it does not stop the job from completing, but logs the failure.

Property	Default Value	Notes
after_script	None	Optional array of commands to execute after job completion.

6. Setting Job Images

Property	Value	Description
image	`alpine:latest`	Specifies the Docker image to use for the job's runner
image.name	`node:18`	Name of the Docker image to use
image.entrypoint	`["/bin/sh"]`	Override the default entrypoint of the image

Example: Using a Custom Image

job_name:
  image: node:18
  script:
    - npm install
    - npm test

Note: The image must be accessible to the GitLab runner. For private images, configure authentication in the CI/CD settings.

7. Configuring Job Services

Service	Description	Configuration	Notes
services	List of Docker images to run as services	`services:`	Each service runs in a separate container
service.name	Name of the service container	`name: postgres:13`	Must be a valid Docker image reference
service.alias	Alias to access the service from job	`alias: db`	Used in job scripts to connect to service
service.command	Override default command for service container	`command: ["/entrypoint.sh", "start"]`	Optional, defaults to image's CMD
service.variables	Environment variables to pass to service	`variables:`	Can be used for credentials or config

Example: Using a PostgreSQL Service

services:
  - name: postgres:13
    alias: db
    variables:
      POSTGRES_DB: testdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password

test_job:
  script:
    - echo "Connecting to database at $DB_PORT"

Note: Services are started before the job script and stopped after. They share network namespace with the job.

Warning: Services must be defined at the job level or global level. Nested service definitions are not supported.

8. Setting Job Timeout

Property	Values	Description
timeout	`1 hour`	Maximum time a job can run before being canceled

Example: Setting a 30-minute job timeout

build_job:
  script:
    - echo "Building..."
  timeout: 30 minutes

Note: The timeout value can be specified in minutes, hours, or days using minutes, hours, or days.

9. Using retry for Failed Jobs

Property	Description	Default	Notes
retry	Number of times to retry a job if it fails	0	Must be a non-negative integer

Example: Retry configuration

job_name:
  script:
    - echo "Running job"
  retry: 2

Note: Retries are attempted after a delay, and each retry is counted as a separate job execution in the pipeline logs.

10. Setting Job Tags

Property	Values	Description
tags	`string[]`	Array of tags to match runners with. Each tag must be a string.

Example: Setting Job Tags

job_name:
  tags:
    - linux
    - ruby-3.0
    - postgres-13

Note: Tags must match exactly between job and runner configuration.