Workflow Artifacts and Caching

# CHAPTER 14

Workflow Artifacts and Caching #

1. Introduction #

1. 1. If Job 1 compiles the code, how does Job 2 get the compiled files if the machine was destroyed?

1. 2. If it takes 3 minutes to download 500MB of npm or composer packages, why do we have to download them again for every single commit?

2. Learning Objectives #

• Differentiate between the operational purpose of Artifacts and Caching.

• Use actions/upload-artifact to persist data after a job finishes.

• Use actions/download-artifact to pass data to sequential jobs.

• Use actions/cache to speed up dependency installation times.

• Understand how cache keys are dynamically generated based on lock files.

3. Beginner-Friendly Explanation #

• The Artifact (Passing the Baton): Station 1 bakes a cake. Station 2 frosts the cake. Because Station 1 and Station 2 are in different buildings, Station 1 must put the cake in a delivery box (Upload Artifact) and send it. Station 2 receives the box, opens it (Download Artifact), and applies the frosting. Artifacts are the physical handoff of the final product.

• The Cache (The Tool Shed): Station 1 needs a very specific wrench to fix the oven. The first time, they drive to the hardware store to buy it (takes 30 mins). Before they leave for the day, they put the wrench in a locked shed. The next day, instead of going to the store, they just grab the wrench from the shed (takes 10 seconds). Caching is saving the heavy tools so you don't have to re-download them.

4. Passing Data with Artifacts #

Uploading:

      - name: Save compiled code
        uses: actions/upload-artifact@v4
        with:
          name: my-compiled-app # The label for the box
          path: ./build-output/ # What to put in the box

*Note: Artifacts uploaded during a workflow are visible in the GitHub UI and can be manually downloaded by developers as ZIP files!*

5. Speeding Up Builds with Caching #

How Caching Works: You provide a "Key" (usually a hash of your composer.lock file). GitHub checks its storage: "Do I have a saved folder matching this key?"

• Cache Hit: GitHub instantly copies the saved folder to your runner. composer install finishes in 1 second.

• Cache Miss: GitHub runs composer install normally, and then saves the resulting folder for the next time.

6. Mini Project: Optimize CI Workflow Speed #

Step-by-Step Walkthrough:

1. 1. Create .github/workflows/caching-demo.yml.

1. 2. Paste the following declarative code:

name: Cached PHP Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'

      # Step 1: Attempt to restore the cache BEFORE running composer
      - name: Cache Composer Dependencies
        uses: actions/cache@v4
        with:
          # The physical folder to save/restore
          path: vendor
          # The unique key based on the OS and the hash of the lock file
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          # Fallback key if an exact match isn't found
          restore-keys: |
            ${{ runner.os }}-composer-

      # Step 2: Install dependencies (Will be instantly fast if Cache Hit!)
      - name: Install Dependencies
        run: composer install --prefer-dist --no-progress

*Run this workflow twice. The first run will take normal time. The second run will be significantly faster because the cache was utilized!*

7. Real-World Scenarios #

8. Best Practices #

• Cache Invalidation (The Lock File): In the mini-project, the key was ${{ hashFiles('/composer.lock') }}. This is brilliant engineering. If a developer doesn't add new packages, the hash remains the same, and the cache is used. If a developer runs composer require new-package, the composer.lock file changes. The hash changes. GitHub sees a new key, realizes it's a "Cache Miss", completely ignores the old saved folder, and correctly downloads the new package.

• Artifact Exposure: Artifacts are tied to the repository. If you upload an artifact containing a compiled app with hardcoded API keys, anyone with read access to the GitHub repository can download that ZIP file from the Actions tab and extract the keys. Never include sensitive configuration files in uploaded artifacts.

• Artifact Size Limits: GitHub imposes storage limits on Artifacts. They are meant for passing code, not for storing 100GB database backups. If your pipeline fails during the upload step, check if you are attempting to upload the entire Linux filesystem instead of just a specific ./build/ directory.

• Q: Describe the mechanics of state persistence across parallel and sequential jobs in GitHub Actions. How do you pass a compiled binary from a 'Build' job to a 'Deploy' job?

• Q: A CI pipeline takes 15 minutes to run npm install. Architect the YAML step required to cache the node_modules directory, and explain the cache invalidation strategy ensuring outdated packages are not restored.