How to Persist Files Between Jobs in CircleCI

Workspaces move files between jobs in the same workflow: one job persists a path, a later job attaches it.

Use persist_to_workspace to save files after a job, and attach_workspace in a downstream job to restore them at the same layout.

Persist then attach

The build job persists dist/; the deploy job attaches the workspace and uses it.

jobs:
  build:
    docker: [{ image: cimg/node:20.11 }]
    steps:
      - checkout
      - run: npm ci && npm run build
      - persist_to_workspace:
          root: .
          paths: [dist]
  deploy:
    docker: [{ image: cimg/base:current }]
    steps:
      - attach_workspace:
          at: .
      - run: ./deploy.sh dist/

workflows:
  build-deploy:
    jobs:
      - build
      - deploy:
          requires: [build]

Gotchas

• Workspaces pass files within one workflow run; caches pass dependencies across runs. They are not interchangeable.
• paths are relative to root; attach at the same layout you persisted.
• The downstream job must requires: the producer so it runs after the persist step.

Key takeaways

• Workspaces move files between jobs in a single workflow.
• Persist with a root and paths; attach at the same layout.
• Workspaces differ from caches, which persist across runs.

Related guides