Skip to content

gitflic-ci.yaml Reference Guide

This documentation lists the keywords for configuring your gitflic-ci.yaml file.

Keywords

Keywords Global Job-level Description
stages ✓ Names and execution order of pipeline stages
include ✓ ✓ Include external .yaml files in configuration
image ✓ ✓ Docker image
cache ✓ ✓ List of files/directories to cache between jobs
variables ✓ ✓ Declare variables and list predefined variables available for use
parallel:matrix ✓ Create parallel jobs using variable matrices
stage ✓ Define job stage
scripts ✓ List of shell scripts executed by the agent
before_script ✓ ✓ Shell scripts executed before each job
after_script ✓ ✓ Shell scripts executed after each job
artifacts ✓ Files/directories attached to successful jobs
needs ✓ Array of job names required before current job can run
when ✓ Define job execution conditions
rules ✓ List of conditions affecting job behavior
tags ✓ Job tags for agent selection
allow_failure ✓ Allow pipeline to continue if job fails
except ✓ Branches where job won't be created
only ✓ Branches where job will be created
trigger ✓ Trigger execution of another pipeline
extends ✓ Inherit configurations from other jobs/templates
environment ✓ Define deployment environment for related jobs

stages

Type: Global keyword

Use stages to define the pipeline execution order.

Default stages if undefined: * .pre * build * test * deploy * .post

Stage order determines execution: * Jobs in same stage run in parallel * Next stage begins after previous stage completes successfully * Pipelines with only .pre/.post stages won't run - must have at least one other stage

Example: 

stages:
  - build
  - test
  - deploy

include

Type: Global keyword

Include additional YAML files.

include:local

Include local repository files:

include:
  - local:
      - "gitflic-1.yaml"
      - "gitflic-2.yaml"

include:project

Include files from other repositories:

include:
  - project:
      project_path: 'my-group/my-project'
      ref: v1.0.0
      file:
        - 'gitflic-ci.yaml'

include:remote

Include remote files (Self-hosted only):

include:
  - remote:
    - "https://external/link/file1.yaml"

Using variables in include

Supports: * Project variables * YAML-defined variables * Predefined variables * Trigger variables * Pipeline scheduler variables

Example: 

variables:
  project_path: "adminuser/include"
  remote_include: "https://external/link/file1.yaml"

include:
  - project:
      project_path: '$project_path'
      ref: '$CI_COMMIT_REF_NAME'
      file:
        - 'gitflic-ci.yaml'
  - remote:
    - "$remote_include"

image

Type: Global or job-level

Specify Docker image for pipeline/job.

Global example: 

image: maven:3.8.5-openjdk-11-slim

Job example: 

job:
  stage: build
  image: maven:3.8.5-openjdk-11-slim

image:name

Image name (same as image keyword)

Example: 

job:
  image:
    name: maven:3.8.5-openjdk-11-slim

image:entrypoint

Container entrypoint command/script

Example: 

job:
  image:
    name: maven:3.8.5-openjdk-11-slim
    entrypoint: [""]

image:docker

Additional Docker options:

job:
  image:
    docker:
      platform: arm64
      user: gitflic

image:pull_policy

Image pull policy: * always (default) * if-not-present * never

Example: 

job:
  image:
    name: maven:3.8.5-openjdk-11-slim
    pull_policy: if-not-present

cache

Type: Global or job-level

Cache files/directories between jobs/pipelines.

cache: []

Disable cache for specific job.

cache:paths

Relative paths to cache:

cache:
  paths:
    - .m2/repository/
    - core/target/

cache:key

Unique cache identifier. Default key: default.

Example: 

cache:
  key:
    - test
  paths:
    - desktop/target/

variables

Type: Global or job-level

Declare CI/CD variables.

Example: 

job_with_variables:
  variables:
    VAR: "Hello, World!"
  scripts:
    - echo "$VAR"

CI/CD Variables

Variable sources: * UI-defined (can be masked) * Pipeline scheduler variables * Manually created pipeline variables * Predefined variables * Global YAML variables * Job-level YAML variables

Predefined Variables
Variable Description
CI_PROJECT_URL Project URL
CI_COMMIT_REF_NAME Branch/tag name
CI_COMMIT_SHA Full commit hash
CI_PIPELINE_ID Pipeline UUID
CI_ENVIRONMENT_NAME Environment name
KUBECONFIG Kubernetes config
Merge Request Variables

Available in merge pipelines:

Variable Description
CI_MERGE_REQUEST_ID MR UUID
CI_MERGE_REQUEST_PROJECT_ID Project UUID
Pipeline Source Values
  • push - Code push
  • parent_pipeline - Triggered pipeline
  • schedule - Scheduled pipeline
  • web - Manual web trigger
  • api - API trigger
  • merge_request_event - MR event
Pipeline Type Values
  • branch_pipeline
  • tag_pipeline
  • merge_request_pipeline
  • merge_result_pipeline
  • train_car_pipeline
Prefill Variables

Define variables with descriptions/options:

variables:
  VAR1:
    description: "Variable without default"
  VAR2:
    description: "Variable with default"
    value: "test-value"
  VAR3:
    description: "Selection variable"
    value: "1-value"
    options:
      - "1-value"
      - "2-value"
Variable Precedence

Priority order: 1. Pipeline creation/scheduler variables 2. Project UI variables 3. parallel:matrix variables 4. Job-level YAML variables 5. Global YAML variables 6. Predefined variables

parallel:matrix

Type: Job-level

Create multiple job instances with different variable values.

Limitations: * Max 200 jobs * Reference matrix jobs in needs with full name

Example: 

matrix_jobs:
  parallel:
    matrix:
      - PROVIDER: ["aws", "gcp"]
        STACK: ["frontend", "backend"]

stage

Type: Job-level

Define job stage.

Example: 

job:
  stage: build

scripts

Type: Job-level

Commands executed by agent.

Example: 

job:
  scripts:
    - echo "Hello"
    - make build

before_script

Type: Global or job-level

Commands executed before main job scripts.

Example: 

job:
  before_script:
    - apt-get update
  scripts:
    - make test

after_script

Type: Global or job-level

Commands executed after main job scripts.

Example: 

job:
  scripts:
    - make build
  after_script:
    - make clean

artifacts

Type: Job-level

Files/directories attached to successful jobs.

artifacts:paths

Relative paths to artifacts:

artifacts:
  paths:
    - bin/
    - output/

artifacts:name

Artifact name:

artifacts:
  name: "build_output"
  paths:
    - bin/

artifacts:reports

Upload reports:

artifacts:
  reports:
    sast:
      paths: 
        - sast_report.json
    junit:
      paths:
        - test-results/*.xml

artifacts:expire_in

Artifact retention period:

artifacts:
  expire_in: 1 week

needs

Type: Job-level

Define job dependencies.

Example: 

test_job:
  needs: [build_job]

needs:parallel:matrix

Reference matrix jobs:

job-2:
  needs:
    - job: job-1
      parallel:
        matrix:
          - PROVIDER: aws
            STACK: frontend

when

Type: Job-level

Job execution conditions: * on_success (default) * manual

Example: 

deploy:
  when: manual

rules

Type: Job-level

Conditional job creation.

Example: 

job:
  rules:
    - if: $CI_COMMIT_REF_NAME == "main"
      when: never
    - if: $CI_COMMIT_TAG
    - when: manual

rules:if

Condition expressions: * String comparison: $VAR == "value" * Variable comparison: $VAR1 == $VAR2 * Existence check: $VAR != null * Regex matching: $VAR =~ /^feature/ * Logical combinations: $VAR1 && ($VAR2 || $VAR3)

rules:changes

Run job when files change:

rules:
  - changes:
      paths:
        - Dockerfile

rules:changes:compare_to

Compare changes to specific ref:

rules:
  - changes:
      paths:
        - src/*
      compare_to: "develop"

rules:allow_failure

Override job's allow_failure.

rules:variables

Set job variables:

rules:
  - if: $CI_COMMIT_TAG
    variables:
      DEPLOY_ENV: "production"

rules:when

Override job's when: * never * manual * on_success

tags

Type: Job-level

Agent selection tags.

Example: 

job:
  tags:
    - docker
    - linux

allow_failure

Type: Job-level

Continue pipeline if job fails: * true * false (default)

except

Type: Job-level

Branches to exclude job from.

Example: 

job:
  except:
    - main

only

Type: Job-level

Branches to include job in.

Example: 

job:
  only: 
    - feature/*

trigger

Type: Job-level

Trigger another pipeline.

Requirements: * User must have Developer+ role in child project * Cannot use with script

Example: 

trigger-job:
  trigger:
    project: group/project
    strategy: depend
    forward:
      yaml_variables: true

extends

Type: Job-level

Inherit configurations.

Example: 

.template:
  scripts:
    - echo "Template script"

job:
  extends: .template
  scripts:
    - echo "Job script"

environment

Type: Job-level

Define deployment environment.

environment:name

Environment name.

Example: 

environment:
  name: production

environment:url

Environment URL.

Example: 

environment:
  url: https://prod.example.com

environment:on_stop

Stop environment job.

Example: 

deploy:
  environment:
    on_stop: stop_env

stop_env:
  environment:
    action: stop

environment:action

Environment interaction: * start (default) * prepare * stop * verify * access

environment:deployment_tier

Deployment tier: * production * staging * testing * development * other (default)

services

Type: Job-level

Additional Docker containers.

Example: 

job:
  services:
    - postgres:latest
    - name: redis
      alias: cache

Docker-in-Docker

Requires privileged mode in agent config:

docker.privileged=true

Automatic Translation!

This page was automatically translated. The text may contain inaccuracies