Skip to content
GitRiverGitRiver
RU
Navigation

CI/CD: Reference

Complete CI/CD format reference: matrix, concurrency, retry, outputs, variables

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

  1. DB variables (from repository settings)
  2. Global env: (top-level workflow)
  3. Job-level env:
  4. Predefined CI_*
  5. Interpolation (resolving chains $A -> $B -> value, up to 10 iterations)
  6. 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