CircleCI Workspaces: Passing Build Artifacts Between Jobs

Workspaces vs caching vs artifacts

| | Workspace | Cache | Artifacts | |---|---|---|---| | Scope | Within one workflow | Across workflow runs | Stored after workflow | | Mutable | Yes — jobs can append | No (immutable per key) | No | | Use case | Pass compiled output between jobs | Reuse dependencies across runs | Download results, test reports | | Retention | Workflow lifetime + 15 days for rerun | 15 days per access | 30 days (configurable) |

Workspaces solve the job isolation problem: by default, each CircleCI job runs in a fresh container with no shared filesystem. If a build job compiles binaries that a test job needs, workspaces carry those files across.

persist_to_workspace and attach_workspace

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm ci
      - run: npm run build   # outputs to dist/
      - persist_to_workspace:
          root: .            # workspace root is current directory
          paths:
            - dist           # persist only the built output
            - node_modules   # persist deps if downstream jobs need them

  test:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - attach_workspace:
          at: .              # restore to current directory
      - run: npm test        # dist/ and node_modules/ are now available

  deploy:
    docker:
      - image: cimg/node:20.10
    steps:
      - attach_workspace:
          at: .
      - run: npm run deploy  # uses dist/ from build job

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires:
            - build          # runs after build completes
      - deploy:
          requires:
            - build          # can run in parallel with test
          filters:
            branches:
              only: main

test and deploy both depend on build, but they're independent of each other — CircleCI runs them in parallel after build completes.

Parallel test splitting with workspaces

Workspaces also enable fan-out patterns: a setup job prepares the test environment once, then multiple parallel test jobs pick up the same workspace:

jobs:
  setup:
    docker:
      - image: cimg/python:3.11
    steps:
      - checkout
      - run: pip install -r requirements.txt
      - persist_to_workspace:
          root: .
          paths:
            - .venv
            - tests

  test-unit:
    docker:
      - image: cimg/python:3.11
    steps:
      - attach_workspace:
          at: .
      - run: python -m pytest tests/unit/ --junitxml=test-results/unit.xml
      - store_test_results:
          path: test-results

  test-integration:
    docker:
      - image: cimg/python:3.11
    steps:
      - attach_workspace:
          at: .
      - run: python -m pytest tests/integration/ --junitxml=test-results/integration.xml
      - store_test_results:
          path: test-results

workflows:
  test-pipeline:
    jobs:
      - setup
      - test-unit:
          requires:
            - setup
      - test-integration:
          requires:
            - setup

Both test jobs run in parallel after setup, sharing the same installed .venv. This halves test time compared to sequential runs that each reinstall dependencies.

# Bad: persists everything including .git
- persist_to_workspace:
    root: .
    paths:
      - .

# Good: persist only what downstream jobs need
- persist_to_workspace:
    root: .
    paths:
      - dist
      - package.json
      - package-lock.json