CI/CD: Reference

Concurrency Management (`concurrency`)

concurrency:
  group: deploy-$CI_COMMIT_BRANCH
  cancel_in_progress: true

When a new run starts in the same group - the previous one is automatically cancelled.

Run Condition (`if`)

jobs:
  deploy:
    if: $CI_COMMIT_BRANCH == "main"
    steps:
      - run: ./deploy.sh

  notify-on-fail:
    if: failure()
    needs: [deploy]
    steps:
      - run: curl -X POST $SLACK_WEBHOOK

Expression	Description
`$VAR == "value"`	String comparison
`$VAR != "value"`	Inequality
`$VAR =~ /pattern/`	Regex match
`$VAR`	Defined and not empty
`!expr`	Negation
`expr1 && expr2`	Logical AND
`expr1 \|\| expr2`	Logical OR
`success()`	All previous jobs succeeded
`failure()`	At least one previous job failed
`always()`	Always execute
`cancelled()`	Pipeline was cancelled

Precedence: || < && < comparison < !

Rules (Run Rules)

rules:
  - if: "$CI_PIPELINE_SOURCE == 'push' && $CI_COMMIT_BRANCH == 'main'"
    when: always
  - changes:
      - "src/**"
      - "*.rs"
    when: manual
  - when: never

Values for when: always, never, manual, on_success, on_failure.

Matrix (Matrix Builds)

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu, alpine]
        rust: ['1.80', '1.93', stable]
      fail_fast: false
      max_parallel: 4
    image: rust:${{ matrix.rust }}
    steps:
      - run: cargo test

Generates a job for each combination. Values are accessible via ${{ matrix.<key> }}.

include / exclude

strategy:
  matrix:
    os: [ubuntu, alpine]
    rust: [stable, nightly]
    include:
      - os: ubuntu
        rust: nightly
        features: experimental
    exclude:
      - os: alpine
        rust: nightly

Retry (Auto-Retry)

jobs:
  test:
    retry:
      max: 2
      when: [script_failure, stuck_or_timeout_failure]
    steps:
      - run: cargo test

Conditions: script_failure, stuck_or_timeout_failure, always (empty list = always).

allow_failure

jobs:
  lint:
    allow_failure: true
    steps:
      - run: cargo clippy -- -D warnings

timeout

jobs:
  build:
    timeout: 30m
    steps:
      - run: cargo build --release

Formats: 30s, 10m, 1h, 1h30m. Default: 1h. Maximum: 6h.

interruptible

jobs:
  test:
    interruptible: true
    steps:
      - run: cargo test

On a new push to the same ref - the running job is automatically cancelled.

needs (DAG Dependencies)

jobs:
  deploy:
    needs:
      - job: build
        optional: false
      - test
    steps:
      - run: ./deploy.sh

Supports optional: true - the dependency doesn’t break the pipeline if the dependent job was filtered out by rules.

Job Outputs

Jobs can pass data via the $CI_OUTPUT file:

jobs:
  prepare:
    steps:
      - run: |
          VERSION=$(cat VERSION)
          echo "version=$VERSION" >> $CI_OUTPUT

  deploy:
    needs: [prepare]
    steps:
      - run: echo "Deploying $NEEDS_PREPARE_OUTPUTS_VERSION"

Predefined Variables

Commit

Variable	Description
`CI_COMMIT_SHA`	Full commit SHA
`CI_COMMIT_SHORT_SHA`	First 7 characters of SHA
`CI_COMMIT_BRANCH`	Branch (on push to a branch)
`CI_COMMIT_TAG`	Tag (on tag push)
`CI_COMMIT_REF_NAME`	Full ref name (`refs/heads/main` or `refs/tags/v1.0`)
`CI_COMMIT_REF_SLUG`	URL-safe ref slug (lowercase, max 63 characters)
`CI_COMMIT_MESSAGE`	Commit message

Repository

Variable	Description
`CI_REPOSITORY_NAME`	Repository name
`CI_REPOSITORY_OWNER`	Owner
`CI_REPOSITORY_FULL_NAME`	owner/repo
`CI_REPOSITORY_URL`	HTTPS URL of the repository

Pipeline

Variable	Description
`CI`	Always `true`
`CI_PIPELINE_ID`	Pipeline ID
`CI_PIPELINE_SOURCE`	Source (`push`, `pull_request`, `schedule`, `web`)
`CI_PIPELINE_URL`	Pipeline URL in the interface

Job

Variable	Description
`CI_JOB_ID`	Current job ID
`CI_JOB_NAME`	Current job name
`CI_JOB_TOKEN`	JWT token for Registry and API access

Container Registry

Variable	Description
`CI_REGISTRY`	Container Registry address
`CI_REGISTRY_IMAGE`	registry/owner/repo
`CI_REGISTRY_USER`	Registry login
`CI_REGISTRY_PASSWORD`	Registry token (= CI_JOB_TOKEN)
`CI_SERVER_URL`	GitRiver base URL

Workspace

Variable	Description
`CI_WORKSPACE`	Working directory
`CI_OUTPUT`	Path to outputs file

Pull Request

Variable	Description
`CI_PULL_REQUEST_NUMBER`	PR number
`CI_PULL_REQUEST_SOURCE`	Source branch
`CI_PULL_REQUEST_TARGET`	Target branch

Repository Variables

Configured in Settings / CI/CD / Variables:

Name - name
Value - value
Masked - hide in logs ([MASKED])

Variable Precedence

DB variables (from repository settings)
Global env: (top-level workflow)
Job-level env:
Predefined CI_*
Interpolation (resolving chains $A -> $B -> value, up to 10 iterations)
Registry variables (CI_REGISTRY_*)

4 levels in the hierarchy: instance -> group -> repository -> environment.

Multiple Workflow Files

.gitriver/
  workflows/
    ci.yml
    release.yml
    nightly.yml
    deploy.yml

Each file is an independent workflow. On push, GitRiver checks all files and runs those whose on: match.

Limits

Parameter	Limit
Workflow files	20 per repository
Jobs per workflow	50
Steps per job	100
`needs` depth levels	10
Matrix combinations	256
Job timeout (max)	6 hours
Job timeout (default)	1 hour
Cron interval (min)	15 minutes
Patterns in paths	100

Concurrency Management (concurrency)

Run Condition (if)