GitLab CI/CD

https://docs.gitlab.com/ci
Admin
GitLab CI/CD is a continuous integration and deployment platform that enables automated building,...
Tokens:917,217
Snippets:6,405
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Immediate start with `needs: []` YAML example

Source: https://docs.gitlab.com/ci/yaml/needs

Shows how to use `needs: []` to make jobs start immediately when the pipeline is created, without waiting for other jobs or stages. In this example, `lint_yaml` and `lint_code` start immediately, while `deploy_app` waits for all earlier stages.

```yaml
stages:
  - build
  - test
  - deploy

build_app:
  stage: build
  script: echo "Building app..."

test_app:
  stage: test
  script: echo "Testing app..."

lint_yaml:
  stage: test
  needs: []
  script: echo "Linting YAML..."

lint_code:
  stage: test
  needs: []
  script: echo "Linting code..."

deploy_app:
  stage: deploy
  script: echo "Deploying app..."

```

--------------------------------

### Example of `start_in` keyword

Source: https://docs.gitlab.com/ci/yaml

Example of the `start_in` keyword with `when: delayed`. The `deploy_production` job starts 30 minutes after the previous stage completes. `start_in` only works with `when: delayed`; otherwise the configuration is invalid.

```yaml
deploy_production:
  stage: deploy
  script:
    - echo "Deploying to production"
  when: delayed
  start_in: 30 minutes

```

--------------------------------

### Immediate start execution order (Mermaid graph)

Source: https://docs.gitlab.com/ci/yaml/needs

Shows the execution order for the immediate start example, with jobs starting as early as possible. The graph illustrates that `build_app`, `lint_yaml`, and `lint_code` start at pipeline start, while `test_app` waits for `build_app` and `deploy_app` waits for `test_app`.

```mermaid
graph LR
  start["Pipeline Start"]

  start --> build_app["build_app"]
  start --> lint_yaml["lint_yaml"]
  start --> lint_code["lint_code"]

  build_app --> test_app["test_app"]
  test_app --> deploy_app["deploy_app"]

```

--------------------------------

### Immediate start pipeline view (Mermaid graph)

Source: https://docs.gitlab.com/ci/yaml/needs

Shows the pipeline view for the immediate start example, with jobs grouped in stages. The graph illustrates that `build_app` and the lint jobs start immediately, while `test_app` waits for `build_app` and `deploy_app` waits for `test_app`.

```mermaid
graph LR
  subgraph build["Build Stage"]
    build_app["build_app"]
  end
  subgraph test["Test Stage"]
    test_app["test_app"]
    lint_yaml["lint_yaml"]
    lint_code["lint_code"]
  end
  subgraph deploy["Deploy Stage"]
    deploy_app["deploy_app"]
  end

  build_app --> test_app
  test_app --> deploy_app

```

--------------------------------

### Example .gitlab-ci.yml with needs keyword

Source: https://docs.gitlab.com/ci/pipelines/pipeline_architectures

A complete GitLab CI/CD configuration showing how to use the `needs` keyword to define job dependencies. Use this when you want jobs to start as soon as their dependencies finish, rather than waiting for all jobs in the same stage. The example defines build, test, and deploy stages with jobs that depend on each other, allowing faster jobs to run earlier.

```yaml
stages:
  - build
  - test
  - deploy

default:
  image: alpine

build_a:
  stage: build
  script:
    - echo "This job builds something quickly."

build_b:
  stage: build
  script:
    - echo "This job builds something else slowly."

test_a:
  stage: test
  needs: [build_a]
  script:
    - echo "This test job will start as soon as build_a finishes."
    - echo "It will not wait for build_b, or other jobs in the build stage, to finish."

test_b:
  stage: test
  needs: [build_b]
  script:
    - echo "This test job will start as soon as build_b finishes."
    - echo "It will not wait for other jobs in the build stage to finish."

deploy_a:
  stage: deploy
  needs: [test_a]
  script:
    - echo "Since build_a and test_a run quickly, this deploy job can run much earlier."
    - echo "It does not need to wait for build_b or test_b."
  environment: production

deploy_b:
  stage: deploy
  needs: [test_b]
  script:
    - echo "Since build_b and test_b run slowly, this deploy job will run much later."
  environment: production
```

--------------------------------

### Install dependencies in before_script

Source: https://docs.gitlab.com/ci/examples/deployment/composer-npm-deploy

Installs git, zip, unzip, Node.js, npm, and Composer in the before_script section.

```yaml
before_script:
  - apt-get update
  - apt-get install -y git zip unzip nodejs npm
  - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
  - php composer-setup.php
  - php -r "unlink('composer-setup.php');"
```

--------------------------------

### before_script for SSH agent setup in .gitlab-ci.yml

Source: https://docs.gitlab.com/ci/jobs/ssh_keys

Add this before_script to your .gitlab-ci.yml to install and start ssh-agent, load the SSH private key from the SSH_PRIVATE_KEY CI/CD variable, and set up the ~/.ssh directory. It assumes a Debian-based image and that the job can install packages. The script includes commented-out git config commands for optional user identity setup.

```yaml
before_script:
  ##
  ## Install ssh-agent if not already installed, it is required by Docker.
  ## (change apt-get to yum if you use an RPM-based image)
  ##
  - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'

  ##
  ## Run ssh-agent (inside the build environment)
  ##
  - eval $(ssh-agent -s)

  ##
  ## Give the right permissions, otherwise ssh-add will refuse to add files
  ## Add the SSH key stored in SSH_PRIVATE_KEY file type CI/CD variable to the agent store
  ##
  - chmod 400 "$SSH_PRIVATE_KEY"
  - ssh-add "$SSH_PRIVATE_KEY"

  ##
  ## Create the SSH directory and give it the right permissions
  ##
  - mkdir -p ~/.ssh
  - chmod 700 ~/.ssh

  ##
  ## Optionally, if you use Git commands, set the user name and email.
  ##
  # - git config --global user.email "user@example.com"
  # - git config --global user.name "User name"
```

--------------------------------

### Create main.go (Go)

Source: https://docs.gitlab.com/ci/components/examples

Example Go source file that prints 'Hello, CI/CD Component' to demonstrate the component's functionality.

```go
// Specify the package, import required packages
// Create a main function
// Inside the main function, print "Hello, CI/CD Component"

package main

import "fmt"

func main() {
  fmt.Println("Hello, CI/CD Component")
}
```

--------------------------------

### GitLab CI job to install CA certificate in Docker-in-Docker service container

Source: https://docs.gitlab.com/ci/docker/docker_build_troubleshooting

Example GitLab CI job configuration that installs a custom CA certificate in the docker:19.03-dind service container before starting the Docker daemon. Uses the CA_CERTIFICATE variable and runs docker commands in the script.

```yaml
image_build:
  stage: build
  image:
    name: docker:19.03
  variables:
    DOCKER_HOST: tcp://localhost:2375
    DOCKER_TLS_CERTDIR: ""
    CA_CERTIFICATE: "$CA_CERTIFICATE"
  services:
    - name: docker:19.03-dind
      command:
        - /bin/sh
        - -c
        - |
          echo "$CA_CERTIFICATE" > /usr/local/share/ca-certificates/custom-ca.crt && \
          update-ca-certificates && \
          dockerd-entrypoint.sh || exit
  script:
    - docker info
    - docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD $DOCKER_REGISTRY
    - docker build -t "${DOCKER_REGISTRY}/my-app:${CI_COMMIT_REF_NAME}" .
    - docker push "${DOCKER_REGISTRY}/my-app:${CI_COMMIT_REF_NAME}"
```

--------------------------------

### Create sample main.go entry point

Source: https://docs.gitlab.com/ci/components/examples/index.md

Defines a basic Go application entry point used to verify Go CI/CD component build and test jobs.

```go
// Specify the package, import required packages
// Create a main function
// Inside the main function, print "Hello, CI/CD Component"

package main

import "fmt"

func main() {
  fmt.Println("Hello, CI/CD Component")
}
```

--------------------------------

### Initialize Docusaurus site with npm

Source: https://docs.gitlab.com/ci/quick_start/tutorial/index.md

Navigates into the project directory and launches the interactive Docusaurus initialization wizard. Use default options when prompted.

```shell
cd pipeline-tutorial
npm init docusaurus
```

--------------------------------

### workflow:auto_cancel:on_job_failure example

Source: https://docs.gitlab.com/ci/yaml

Configures the pipeline to cancel all running jobs and prevent subsequent stages from starting when any job fails. In this example, if job2 fails, job1 is canceled if still running and job3 does not start.

```yaml
stages: [stage_a, stage_b]

workflow:
  auto_cancel:
    on_job_failure: all

job1:
  stage: stage_a
  script: sleep 60

job2:
  stage: stage_a
  script:
    - sleep 30
    - exit 1

job3:
  stage: stage_b
  script:
    - sleep 30

```

--------------------------------

### Initialize Go CI/CD component repository structure

Source: https://docs.gitlab.com/ci/components/examples/index.md

Sets up the Git repository, required metadata files, and templates directory structure for the new CI/CD component.

```shell
git init

mkdir templates
touch templates/{format,build,test}.yml

touch README.md LICENSE.md .gitlab-ci.yml .gitignore

git add -A
git commit -avm "Initial component structure"

git remote add origin https://gitlab.example.com/components/golang.git

git push
```

--------------------------------

### Install Node.js, system utilities, and Composer in before_script

Source: https://docs.gitlab.com/ci/examples/deployment/composer-npm-deploy/index.md

Installs git, zip utilities, Node.js, and npm using apt-get, and downloads Composer via PHP script in the before_script section.

```yaml
before_script:
  - apt-get update
  - apt-get install -y git zip unzip nodejs npm
  - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
  - php composer-setup.php
  - php -r "unlink('composer-setup.php');"
```

--------------------------------

### allow_failure: true example

Source: https://docs.gitlab.com/ci/yaml

Shows how to set allow_failure: true on a job so the pipeline continues even if that job fails. In this example, job1 and job2 run in parallel; if job1 fails, the deploy stage does not start, but if job2 fails, the deploy stage can still start.

```yaml
job1:
  stage: test
  script:
    - execute_script_1

job2:
  stage: test
  script:
    - execute_script_2
  allow_failure: true

job3:
  stage: deploy
  script:
    - deploy_to_staging
  environment: staging
```

--------------------------------

### Using Composer in GitLab CI

Source: https://docs.gitlab.com/ci/examples/php

Example of using Composer to install PHP dependencies before running tests. Includes caching the vendor/ directory and verifying the Composer installer.

```yaml
# Composer stores all downloaded packages in the vendor/ directory.
# Do not use the following if the vendor/ directory is committed to
# your git repository.
default:
  cache:
    paths:
      - vendor/
  before_script:
    # Install composer dependencies
    - wget https://composer.github.io/installer.sig -O - -q | tr -d '\n' > installer.sig
    - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
    - php -r "if (hash_file('SHA384', 'composer-setup.php') === file_get_contents('installer.sig')) { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
    - php composer-setup.php
    - php -r "unlink('composer-setup.php'); unlink('installer.sig');"
    - php composer.phar install

```

--------------------------------

### GitLab CI/CD .gitlab-ci.yml equivalent

Source: https://docs.gitlab.com/ci/migration/github_actions

Equivalent GitLab CI/CD configuration using stages and script to echo Hello World.

```yaml
stages:
  - hello

hello:
  stage: hello
  script:
    - echo "Hello World"

```

--------------------------------

### Install custom PHP extension with PECL

Source: https://docs.gitlab.com/ci/examples/php

Run this command to install a custom PHP extension using PECL. It is recommended to execute this once during build environment setup, not in .gitlab-ci.yml.

```shell
pecl install <extension>
```

--------------------------------

### Initialize Go module (shell)

Source: https://docs.gitlab.com/ci/components/examples

Command to initialize a Go module for the component's Go project, using the example URL.

```shell
go mod init example.gitlab.com/components/golang
```

--------------------------------

### Log in to MySQL as root

Source: https://docs.gitlab.com/ci/services/mysql/index.md

Starts a MySQL session as root. You will be prompted for the root password you set during installation.

```shell
mysql -u root -p
```

--------------------------------

### Install PostgreSQL on Shell executor

Source: https://docs.gitlab.com/ci/services/postgres

Installs PostgreSQL server, client, and libpq-dev on a manually configured server using apt.

```shell
sudo apt-get install -y postgresql postgresql-client libpq-dev
```

--------------------------------

### Configure carbon-report CI/CD job in .gitlab-ci.yml

Source: https://docs.gitlab.com/ci/sustainability/carmen/index.md

Defines a pipeline job that installs prerequisite packages, clones Carmen, installs required Node.js and Python packages, runs carbon-daemon on example data, and captures the generated output as an artifact.

```yaml
carbon-report:
  image: python:3.12
  before_script:
    - apt-get update && apt-get install -y nodejs npm git lsb-release
    - git clone https://github.com/Green-Software-Foundation/if-carmen.git
    - npm install -g "@grnsft/if@1.0.0" "@grnsft/if-plugins@0.3.2" "@grnsft/if-unofficial-plugins@0.3.1"
    - pip install --upgrade pip && pip install -e $CI_PROJECT_DIR/if-carmen
  script:
    - cd $CI_PROJECT_DIR/if-carmen/example-data && carbon-daemon
  artifacts:
    paths:
      - if-carmen/example-data/output/
    expire_in: 1 week
```

--------------------------------

### Use npm ci in a CI/CD job

Source: https://docs.gitlab.com/ci/pipeline_security

Example CI/CD job that uses npm ci to install dependencies from the lock file, ensuring exact versions.

```yaml
javascript-job:
  script:
    - npm ci
```

--------------------------------

### Example README and component directory structure

Source: https://docs.gitlab.com/ci/components

Shows a recommended file layout for a component project with a README linking to per-component docs. Use this structure when a component needs additional instructions beyond the main README.

```text
README.md    # with links to the specific docs.md
templates/
├── component-1/
│   ├── template.yml
│   └── docs.md
└── component-2/
    ├── template.yml
    └── docs.md

```

--------------------------------

### Identifier examples

Source: https://docs.gitlab.com/ci/functions/moa

Identifiers reference values from the expression context. They start with a letter or underscore and can contain letters, digits, and underscores. Identifiers are case-sensitive, so foo, Foo, and FOO are different.

```yaml
${{ env }}
${{ my_variable }}
```

--------------------------------

### Install MySQL server on Shell executor

Source: https://docs.gitlab.com/ci/services/mysql/index.md

Installs MySQL server, client, and development libraries on a manually-configured server using apt-get.

```shell
sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
```

--------------------------------

### needs:optional example: optional job in needs

Source: https://docs.gitlab.com/ci/yaml

Example of needs:optional. When test-job2 is not added to the pipeline (e.g., non-default branch), deploy-job waits only for test-job1, and review-job starts immediately like needs: []. If a needed job has optional: false but is not added, the pipeline fails with an error. Cannot be used with needs:parallel:matrix.

```yaml
build-job:
  stage: build

test-job1:
  stage: test

test-job2:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
    - job: test-job1
  environment: production

review-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
  environment: review

```

--------------------------------

### Expanded job template configuration example

Source: https://docs.gitlab.com/ci/yaml/yaml_optimization/index.md

Shows the fully expanded CI/CD pipeline representation of the YAML anchor map merging example.

```yaml
.job_template:
  image: ruby:2.6
  services:
    - postgres
    - redis

test1:
  image: ruby:2.6
  services:
    - postgres
    - redis
  script:
    - test1 project

test2:
  image: ruby:2.6
  services:
    - postgres
    - redis
  script:
    - test2 project
```

--------------------------------

### Split long commands with `>` folded block scalar

Source: https://docs.gitlab.com/ci/yaml/script

The `>` (folded) block scalar indicator treats empty lines between sections as the start of a new command. The second YAML example shows the equivalent behavior without the `>` or `|` indicators, where GitLab concatenates non-empty lines. The shell output shows the rendered job log for both examples.

```yaml
job:
  script:
    - >
      echo "First command line
      is split over two lines."

      echo "Second command line."

```

```yaml
job:
  script:
    - echo "First command line
      is split over two lines."

      echo "Second command line."

```

```shell
$ echo First command line is split over two lines. # collapsed multiline command
First command line is split over two lines.
Second command line.

```

--------------------------------

### Configure .gitlab-ci.yml for hosted runners on Windows

Source: https://docs.gitlab.com/ci/runners/hosted_runners/windows/index.md

Get started with hosted runners on Windows by tagging jobs with `saas-windows-medium-amd64`. Jobs execute in an elevated admin process on a newly provisioned virtual machine.

```yaml
.windows_job:
  tags:
    - saas-windows-medium-amd64
  before_script:
    - Set-Variable -Name "time" -Value (date -Format "%H:%m")
    - echo ${time}
    - echo "started by ${GITLAB_USER_NAME} / @${GITLAB_USER_LOGIN}"

build:
  extends:
    - .windows_job
  stage: build
  script:
    - echo "running scripts in the build job"

test:
  extends:
    - .windows_job
  stage: test
  script:
    - echo "running scripts in the test job"
```
Tokens:
Raw