GitLab CI 速查表:80+ 流水线 YAML 片段、Rules、制品与 API 参考

stages:
  - build
  - test
  - deploy

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    - if: '$CI_COMMIT_TAG'

default:
  image: node:20-alpine
  before_script:
    - npm ci --prefer-offline
  retry:
    max: 2
    when: runner_system_failure
  interruptible: true

include:
  - local: '.gitlab/ci/build.yml'
  - template: 'Security/SAST.gitlab-ci.yml'
  - project: 'my-group/ci-templates'
    ref: main
    file: '/templates/docker-build.yml'

deploy-downstream:
  trigger:
    project: my-group/deploy-repo
    branch: main
    strategy: depend
  variables:
    IMAGE_TAG: $CI_COMMIT_SHA

generate:
  script: python generate_pipeline.py > pipeline.yml
  artifacts:
    paths: [pipeline.yml]

run-child:
  trigger:
    include:
      - artifact: pipeline.yml
        job: generate

stages: [build, test, deploy]

image: alpine:3.19

build-job:
  stage: build
  script:
    - echo "Building…"

test-job:
  stage: test
  script:
    - echo "Testing…"

deploy-job:
  stage: deploy
  script:
    - echo "Deploying…"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

include:
  - component: gitlab.com/components/sast/sast@~latest
    inputs:
      stage: security

test-unit:
  stage: test
  before_script:
    - cp .env.test .env
  script:
    - npm test
  after_script:
    - rm -f .env

lint:
  script: npm run lint
  allow_failure: true

# Allow only specific exit code
dependency-check:
  script: ./check-deps.sh
  allow_failure:
    exit_codes: [2, 3]

deploy:
  script: ./deploy.sh
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

e2e-tests:
  script: npm run test:e2e
  timeout: 2h 30m

unit-tests:
  script: npm test
  timeout: 10 minutes

notify-on-failure:
  script: ./notify.sh
  when: on_failure

deploy-to-prod:
  script: ./deploy-prod.sh
  when: manual
  allow_failure: false

canary-deploy:
  script: ./canary.sh
  when: delayed
  start_in: 30 minutes

deploy-staging:
  script: ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com

deploy-review:
  script: ./deploy.sh review/$CI_COMMIT_REF_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
    on_stop: stop-review

test:
  script: pytest --cov=myapp --cov-report=term-missing
  coverage: '/TOTAL.*s+(d+%)$/'

test-node:
  script: npm test -- --coverage
  coverage: '/Liness*:s*(d+.?d*)%/'

pages:
  stage: deploy
  script:
    - npm run build
    - mv dist/ public/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

deploy:
  script: ./deploy.sh
  inherit:
    default: false
    variables:
      - DEPLOY_TOKEN
      - TARGET_ENV

deploy:
  script: ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - when: never

build-frontend:
  script: npm run build
  rules:
    - changes:
        paths:
          - frontend/**/*
          - package-lock.json
        compare_to: 'refs/heads/main'

docker-build:
  script: docker build .
  rules:
    - exists:
        - Dockerfile
    - exists:
        - 'services/*/Dockerfile'

test-unit:
  stage: test
  needs: [build]

test-e2e:
  stage: test
  needs:
    - job: build
      artifacts: true
    - job: seed-db
      artifacts: false

deploy:
  stage: deploy
  script: ./deploy.sh
  dependencies:
    - build-app

e2e-tests:
  stage: test
  script: npm run test:e2e
  dependencies: []   # don't download any artifacts

# Legacy — prefer rules:
deploy:
  script: ./deploy.sh
  only:
    - main
    - tags
  except:
    - /^experiment/.*/

# Common rule conditions:
rules:
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  - if: '$CI_PIPELINE_SOURCE == "schedule"'
  - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
  - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

build:
  script: docker build -t $IMAGE_TAG .
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      variables:
        IMAGE_TAG: $CI_REGISTRY_IMAGE:latest
    - if: '$CI_COMMIT_TAG'
      variables:
        IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
    - variables:
        IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

variables:
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: "/certs"
  NODE_ENV: production
  FF_USE_FASTZIP: "true"   # GitLab feature flag

test-postgres:
  image: postgres:15
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: ci
    POSTGRES_PASSWORD: ""
    CONN_STR: "postgres://${POSTGRES_USER}@postgres/${POSTGRES_DB}"

build-image:
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

build:
  script:
    - VERSION=$(git describe --tags)
    - echo "VERSION=$VERSION" > build.env
    - echo "IMAGE=$CI_REGISTRY_IMAGE:$VERSION" >> build.env
  artifacts:
    reports:
      dotenv: build.env

deploy:
  script:
    - echo "Deploying $IMAGE version $VERSION"
  needs:
    - job: build
      artifacts: true

variables:
  ENVIRONMENT:
    value: "staging"
    options:
      - "staging"
      - "production"
    description: "Target environment for deployment"
  LOG_LEVEL:
    value: "info"
    description: "Application log level"

download-package:
  script:
    - curl --header "JOB-TOKEN: $CI_JOB_TOKEN"
        "https://gitlab.example.com/api/v4/projects/123/packages/generic/myapp/1.0/app.tar.gz"
        -o app.tar.gz

# In .gitlab-ci.yml, just reference the variable name:
deploy:
  script:
    - curl -H "Authorization: Bearer $DEPLOY_TOKEN" https://api.example.com/deploy
  # DEPLOY_TOKEN is masked in GitLab Settings → CI/CD → Variables

# Branch "feature/my-feature" → "feature-my-feature"
deploy-review:
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
  script:
    - kubectl create namespace $CI_COMMIT_REF_SLUG || true

build:
  script: npm run build
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
    paths:
      - dist/
      - coverage/
    when: always        # upload even if script fails
    expire_in: 1 week

build:
  artifacts:
    paths: [dist/]
    expire_in: 30 days

test:
  artifacts:
    paths: [coverage/]
    expire_in: never    # keep test reports forever

test:
  script:
    - pytest --junitxml=report.xml
    - npm test -- --reporters=junit --outputFile=junit.xml
  artifacts:
    reports:
      junit:
        - report.xml
        - junit.xml

test:
  script: pytest --cov=myapp --cov-report=xml:coverage.xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml

# To consume manually:
semgrep-sast:
  artifacts:
    reports:
      sast: gl-sast-report.json

test:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
    policy: pull-push   # default: download, run, upload

build:
  cache:
    - key:
        files: [package-lock.json]
      paths: [node_modules/]
    - key:
        files: [Gemfile.lock]
      paths: [vendor/bundle/]

build:
  script: npm run build
  artifacts:
    paths: [dist/]
    exclude:
      - dist/**/*.map
      - dist/**/*.test.js

build:
  tags:
    - docker
    - linux

gpu-train:
  tags:
    - gpu
    - cuda-12

test:
  image: python:3.12-slim

build-go:
  image: golang:1.22-alpine

security-scan:
  image:
    name: aquasec/trivy:0.50.1
    entrypoint: [""]

test-integration:
  image: node:20
  services:
    - name: postgres:15
      alias: db
    - name: redis:7-alpine
      alias: cache
  variables:
    POSTGRES_DB: test
    POSTGRES_USER: ci
    DATABASE_URL: "postgres://ci@db/test"

rspec:
  script:
    - bundle exec rspec --format progress
        --only-failures-at-index $((CI_NODE_INDEX - 1))
        --shard-count $CI_NODE_TOTAL
  parallel: 5

build:
  script: make build TARGET=$TARGET ARCH=$ARCH
  parallel:
    matrix:
      - TARGET: [linux, darwin, windows]
        ARCH: [amd64, arm64]
      - TARGET: linux
        ARCH: [386]

# In /etc/gitlab-runner/config.toml:
[[runners]]
  name = "docker-runner"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = true    # needed for DinD

build-image:
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t myapp .
    - docker push myapp

build:
  script: go build ./...
  artifacts:
    untracked: true
    paths:
      - bin/

.deploy-base:
  stage: deploy
  before_script:
    - apt-get install -y curl
  retry:
    max: 2

deploy-staging:
  extends: .deploy-base
  script: ./deploy.sh staging
  environment:
    name: staging

deploy-prod:
  extends: .deploy-base
  script: ./deploy.sh prod
  when: manual

.node-setup: &node-setup
  image: node:20-alpine
  cache:
    key:
      files: [package-lock.json]
    paths: [node_modules/]

test:
  <<: *node-setup
  script: npm test

lint:
  <<: *node-setup
  script: npm run lint

.setup-steps:
  script:
    - apt-get update -qq
    - apt-get install -y curl

.prod-rules:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

deploy:
  script:
    - !reference [.setup-steps, script]
    - ./deploy.sh
  rules: !reference [.prod-rules, rules]

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml
  - template: Code-Quality.gitlab-ci.yml

# Override a template job:
semgrep-sast:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

spec:
  inputs:
    stage:
      default: test
    image:
      default: alpine

---
my-job:
  stage: $[[ inputs.stage ]]
  image: $[[ inputs.image ]]
  script: echo "running"

.docker-login:
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

.only-main:
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

build-image:
  extends:
    - .docker-login
    - .only-main
  script: docker build -t $CI_REGISTRY_IMAGE .

.base-node:
  image: node:20
  cache:
    key:
      files: [package-lock.json]
    paths: [node_modules/]

.mr-only:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

test-on-mr:
  extends:
    - .base-node
    - .mr-only
  script: npm test

deploy-aws:
  id_tokens:
    AWS_OIDC_TOKEN:
      aud: https://sts.amazonaws.com
  script:
    - export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/GitLabCI
    - aws sts assume-role-with-web-identity
        --role-arn $AWS_ROLE_ARN
        --web-identity-token $AWS_OIDC_TOKEN
        --role-session-name gitlab-ci

# In GitLab UI: Settings → CI/CD → Variables
# Variable: PROD_DB_URL
# Environments: production  ← scoped
# Protected: ✓  ← only runs on protected branches

deploy-prod:
  environment: production
  script: ./deploy.sh $PROD_DB_URL  # only available here

deploy:
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops
    API_KEY:
      vault:
        engine:
          name: kv-v2
          path: secrets
        path: myapp/prod
        field: api_key
  script: ./deploy.sh

deploy-review:
  script: kubectl apply -f k8s/review.yaml
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    on_stop: stop-review

stop-review:
  script: kubectl delete namespace $CI_COMMIT_REF_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual

# Reference another project's API using allowlisted CI_JOB_TOKEN:
fetch-shared-lib:
  script:
    - curl --header "JOB-TOKEN: $CI_JOB_TOKEN"
        "$CI_API_V4_URL/projects/456/repository/files/lib.sh/raw?ref=main"
        -o lib.sh

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - template: Security/Container-Scanning.gitlab-ci.yml

default:
  interruptible: true   # applies to all jobs

# Override for deploy jobs that must not be interrupted:
deploy-prod:
  interruptible: false
  script: ./deploy.sh

deploy-prod:
  script: ./deploy.sh production
  resource_group: production-deploy
  environment: production

# Only one deploy-prod can run at a time across all pipelines

git commit -m "chore: update changelog [skip ci]"

# Or use the CI_SKIP variable in API triggers:
curl --request POST \
  --form "token=$CI_JOB_TOKEN" \
  --form "ref=main" \
  --form "variables[CI_SKIP]=true" \
  "https://gitlab.example.com/api/v4/projects/1/trigger/pipeline"

install:
  script: npm ci
  cache:
    key:
      files: [package-lock.json]
    paths: [node_modules/]
    policy: pull-push   # download + upload

test:
  script: npm test
  needs: [install]
  cache:
    key:
      files: [package-lock.json]
    paths: [node_modules/]
    policy: pull        # download only — don't re-upload

variables:
  GIT_DEPTH: 1               # shallow clone — fastest
  GIT_STRATEGY: fetch        # reuse existing checkout

deploy:
  variables:
    GIT_STRATEGY: none       # no checkout needed, uses artifacts only
  script: ./deploy.sh

stages: [build, test, deploy]

build-app:
  stage: build
  script: npm run build

test-unit:
  stage: test
  needs: [build-app]
  script: npm test

test-lint:
  stage: test
  needs: [build-app]
  script: npm run lint

test-e2e:
  stage: test
  needs: [test-unit, test-lint]
  script: npm run test:e2e

deploy:
  stage: deploy
  needs: [test-e2e]
  script: ./deploy.sh

full-test-suite:
  script: npm run test:all
  rules:
    - if: '$CI_COMMIT_MESSAGE =~ /\[full-tests\]/'
    - if: '$CI_COMMIT_BRANCH == "main"'

nightly-security-scan:
  script: ./security-scan.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

curl -X POST \
  --form "token=$TRIGGER_TOKEN" \
  --form "ref=main" \
  --form "variables[DEPLOY_ENV]=production" \
  "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline"

# List recent failed pipelines on main:
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.example.com/api/v4/projects/123/pipelines?ref=main&status=failed&per_page=10"

# Download the entire artifact archive:
curl --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.example.com/api/v4/projects/123/jobs/456/artifacts" \
  -o artifacts.zip

# Download a specific file:
curl --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.example.com/api/v4/projects/123/jobs/456/artifacts/dist/app.js" \
  -o app.js

# List all failed jobs in a pipeline:
curl --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.example.com/api/v4/projects/123/pipelines/789/jobs?scope[]=failed"

curl -X POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "ref": "main",
    "variables": [
      {"key": "DEPLOY_ENV", "value": "production"},
      {"key": "IMAGE_TAG", "value": "v1.2.3"}
    ]
  }' \
  "https://gitlab.example.com/api/v4/projects/123/pipeline"

# Trigger a manual deploy job:
curl -X POST \
  --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.example.com/api/v4/projects/123/jobs/456/play"

#!/bin/bash
PIPELINE_ID=$1
while true; do
  STATUS=$(curl -s --header "PRIVATE-TOKEN: $TOKEN" \
    "https://gitlab.example.com/api/v4/projects/123/pipelines/$PIPELINE_ID" \
    | jq -r '.status')
  echo "Status: $STATUS"
  [[ "$STATUS" =~ ^(success|failed|canceled)$ ]] && break
  sleep 10
done

curl -X POST \
  --header "PRIVATE-TOKEN: $TOKEN" \
  --data "state=success&name=external-quality-check&description=All checks passed" \
  "https://gitlab.example.com/api/v4/projects/123/statuses/$CI_COMMIT_SHA"