gitlab-ci-artifacts-caching

name	gitlab-ci-artifacts-caching
description	Use when configuring artifacts for inter-job data passing or caching for faster builds. Covers cache strategies and artifact management.
allowed-tools	["Read","Write","Edit","Bash","Grep","Glob"]

GitLab CI - Artifacts & Caching

Configure artifacts and caching for efficient pipeline execution.

Artifacts

Basic Artifact Configuration

build:
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

Artifact Reports

test:
  script:
    - npm test -- --coverage
  artifacts:
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

Conditional Artifacts

build:
  artifacts:
    paths:
      - dist/
    when: on_success  # on_success, on_failure, always
    exclude:
      - dist/**/*.map

Artifact Dependencies

build:
  artifacts:
    paths:
      - dist/

test:
  dependencies:
    - build  # Downloads build artifacts
  script:
    - npm test

deploy:
  dependencies: []  # Skip all artifact downloads
  script:
    - ./deploy.sh

Caching

Basic Cache Configuration

default:
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
      - .npm/

Cache Key Strategies

# Per-branch cache
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/

# Lock file based cache
cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/

# Combined key
cache:
  key:
    prefix: ${CI_JOB_NAME}
    files:
      - package-lock.json
  paths:
    - node_modules/

Cache Policy

install:
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
    policy: push  # Only upload cache
  script:
    - npm ci

test:
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
    policy: pull  # Only download cache
  script:
    - npm test

Fallback Keys

cache:
  key: ${CI_COMMIT_REF_SLUG}
  fallback_keys:
    - ${CI_DEFAULT_BRANCH}
    - main
  paths:
    - node_modules/

Distributed Cache (S3)

Configure in GitLab Runner:

[runners.cache]
  Type = "s3"
  Shared = true
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    BucketName = "gitlab-runner-cache"
    BucketLocation = "us-east-1"

Artifacts vs Cache

Feature	Artifacts	Cache
Purpose	Pass data between jobs	Speed up job execution
Storage	GitLab server	Runner local or S3
Reliability	Guaranteed	Best effort
Expiration	Configurable	Configurable
Cross-pipeline	Yes (with dependencies)	Yes (with keys)

Best Practices

1. Use cache for dependencies (node_modules, vendor)
2. Use artifacts for build outputs
3. Set appropriate expiration times
4. Use lock file-based cache keys
5. Exclude source maps and unnecessary files
6. Use policy: pull for jobs that only read cache