Skip to content

7.artifacts-caching.md

Latest commit

 

History

History
128 lines (96 loc) · 3.59 KB

7.artifacts-caching.md

File metadata and controls

128 lines (96 loc) · 3.59 KB

GitHub Actions: Artifacts & Caching

Artifacts let you persist files from a workflow run (like build outputs or test reports). Caching speeds up workflows by reusing dependencies between runs. Both are essential for efficient CI/CD pipelines.

1. Artifacts

  • Artifacts are files or directories produced by a job that you want to keep after the run.
  • Common uses: build outputs, compiled binaries, test reports, logs.
  • Uploaded with actions/upload-artifact and downloaded with actions/download-artifact.
  • Stored for 90 days by default (configurable).

Uploading an artifact

steps:
  - name: Build project
    run: npm run build

  - name: Upload build output
    uses: actions/upload-artifact@v4
    with:
      name: build-output        # Name of the artifact
      path: dist/               # File or folder to upload
      retention-days: 7         # Optional: how long to keep it

Downloading an artifact (in the same or another job)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download build output
        uses: actions/download-artifact@v4
        with:
          name: build-output    # Must match the upload name
          path: dist/           # Where to place the downloaded files

      - name: Deploy
        run: ./deploy.sh

2. Caching

  • Caching saves dependency folders (like node_modules) between workflow runs.
  • Avoids re-downloading the same packages on every run — significantly speeds up pipelines.
  • Uses actions/cache with a cache key to identify what to restore.

Cache Key Strategy

  • The key should include something that changes when dependencies change (e.g., a hash of package-lock.json).
  • If the exact key isn't found, GitHub tries restore-keys as a fallback.

Caching Node.js dependencies

steps:
  - uses: actions/checkout@v4

  - name: Cache node_modules
    uses: actions/cache@v4
    with:
      path: node_modules                          # What to cache
      key: node-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
      restore-keys: |
        node-${{ runner.os }}-                    # Fallback key prefix

  - name: Install dependencies
    run: npm install

  - name: Run tests
    run: npm test

Caching Python dependencies

steps:
  - uses: actions/checkout@v4

  - name: Cache pip packages
    uses: actions/cache@v4
    with:
      path: ~/.cache/pip
      key: pip-${{ runner.os }}-${{ hashFiles('requirements.txt') }}
      restore-keys: |
        pip-${{ runner.os }}-

  - name: Install dependencies
    run: pip install -r requirements.txt

3. Artifacts vs Cache — When to Use Which

Artifacts Cache
Purpose Store build outputs, reports Speed up dependency installation
Shared between Jobs in same/different runs Runs of the same workflow
Lifetime Days (configurable, default 90) 7 days since last access
Example use dist/, test results, logs node_modules/, .cache/pip

Key Rules

  • Artifact names must be unique within a workflow run.
  • Cache keys are immutable — a matching key is restored, never overwritten (a new key creates a new entry).
  • Use hashFiles() in cache keys to automatically invalidate when dependency files change.
  • Cache is not shared across different branches by default (falls back to restore-keys).