GitHub Actions

This activity puts into practice the concepts from the CI/CD Pipelines lecture. Starting from a small Python web application, you will build a pipeline that follows the feedback loop the lecture describes: lint the code, run the tests across two Python versions, build a Docker image, smoke-test the running container, and push it to GitHub Container Registry. By the end, you will have a two-job pipeline with the same dependency pattern and quality gates you would see in a production repository.

What You Will Need

• A GitHub account with a public repository you will create for this activity
• Git configured with your GitHub username and email
• A text editor
• A terminal with bash available

---

Bootstrap the Application

Before writing any workflow YAML, you need something to build and test. You will create a minimal Python web service, a short test file, and a Dockerfile. All three live in the repository root.

1. Create a new public GitHub repository. Go to github.com/new, name it cs312-ci-activity, set visibility to Public and click Create repository.

2. Clone the repository:

   git clone https://github.com/YOUR_GITHUB_USERNAME/cs312-ci-activity.git
   cd cs312-ci-activity

   Replace YOUR_GITHUB_USERNAME with your actual handle.

3. Create app.py:

   from flask import Flask, jsonify
   
   app = Flask(__name__)
   
   
   @app.route("/")
   def index():
       return jsonify({"status": "ok", "version": "1.0.0"})
   
   
   if __name__ == "__main__":
       app.run(host="0.0.0.0", port=8080)

   This is a Flask web application with a single endpoint. When the container runs, GET / returns a JSON object. It is intentionally small: the goal of this activity is the pipeline, not the application.

4. Create test_app.py:

   from app import app
   
   
   def test_index():
       client = app.test_client()
       response = client.get("/")
       assert response.status_code == 200
       assert response.get_json()["status"] == "ok"

   app.test_client() is Flask’s built-in test client. It sends requests to the application without starting a real HTTP server, so the test runs with no ports open and no external dependencies.

5. Create requirements.txt:

   flask==3.1.0
   pytest==8.3.4
   flake8==7.1.0

   Pinning exact versions makes builds reproducible: every run, on every runner, installs the same libraries from the same source.

6. Create the Dockerfile:

   FROM python:3.12-slim
   
   WORKDIR /app
   
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   
   COPY app.py .
   
   EXPOSE 8080
   
   CMD ["python", "app.py"]

   The COPY requirements.txt and RUN pip install steps come before COPY app.py deliberately. Docker builds images layer by layer and caches each layer separately. When only app.py changes, Docker reuses the cached pip layer instead of re-installing every dependency. This is the same principle as pip caching in the Actions workflow you are about to write.

7. Commit and push everything:

   git add app.py test_app.py requirements.txt Dockerfile
   git commit -m "Add application source and Dockerfile"
   git push origin main

---

Your First Workflow: Lint and Test

The cheapest stage of the feedback loop is checking the code without running it. You will create a workflow with one job, quality, that lints the Python source with flake8 and runs the tests with pytest. If either step fails, the pipeline stops here before spending any runner time on a Docker build.

Notice the permissions block near the top of the file. GitHub generates an automatic GITHUB_TOKEN for every workflow run, and repository or organization defaults can still be broader than this workflow actually needs. Explicitly declaring contents: read limits the token to the one permission the quality job requires, which is the least-privilege principle the lecture described applied to a real workflow.

1. Create .github/workflows/ci.yml, creating the .github/workflows/ directories if your editor asks:

   name: CI
   
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
     workflow_dispatch:
   
   permissions:
     contents: read
   
   jobs:
     quality:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
   
         - name: Set up Python
           uses: actions/setup-python@v6
           with:
             python-version: '3.12'
             cache: pip
   
         - name: Install dependencies
           run: pip install -r requirements.txt
   
         - name: Lint
           run: flake8 .
   
         - name: Test
           run: pytest -v

   GitHub recognizes workflow files only under .github/workflows/, which is why the path matters. The cache: pip parameter in actions/setup-python stores pip’s download cache between runs, keyed to a hash of requirements.txt. The first run downloads and saves all packages; every subsequent run restores them instead of pulling from PyPI. You will see a line like Cache restored from key: setup-python-... starting with the second run.

   The workflow_dispatch: entry enables manual runs from the Actions tab, but GitHub exposes the Run workflow button only when the workflow file exists on the repository’s default branch. You will satisfy that requirement in step 3 when you commit and push this file to main.

2. Enable GitHub Actions for the repository. Open your repository on GitHub and click the Actions tab. If GitHub shows a prompt to enable workflows for this new repository, enable them before the next push. If Actions are already enabled, continue to the next step.

3. Commit and push:

   git add .github/workflows/ci.yml
   git commit -m "Add CI workflow with lint and test"
   git push

4. Return to the Actions tab on your repository. You should see a workflow named CI in progress or just finished. Click into it, then click quality to see the job steps.

5. Expand the Lint and Test steps. The Lint step should complete silently: no output means flake8 found no issues. The Test step should print something like:

   test_app.py::test_index PASSED [100%]
   1 passed in 0.11s

   Both steps show checkmarks.

6. Trigger the workflow manually. Return to the Actions tab and click CI in the left sidebar. Because the workflow file now exists on main, you should see a Run workflow button near the top right of the run list. Click it, leave the branch set to main, and click the green Run workflow button. A new run appears in the list labeled with a workflow_dispatch event. Open it: for this workflow, the jobs run the same way as the push-triggered run. The relevant behavior change here is that github.event_name equals workflow_dispatch rather than push. This is how deploy workflows let a human choose when to ship without requiring a code commit.

Think About It

The quality job runs the Lint step before the Test step. What happens to the Test step if Lint fails? How does this connect to the “fail fast” principle the lecture describes? What would the pipeline’s cost look like if Test ran first and generated a large HTML coverage report on every invocation?

---

Building the Docker Image

Passing lint and tests is necessary but not sufficient: the lecture’s feedback loop ends at the registry, not the test runner. You will add a second job, build, that starts only after quality passes and runs only on pushes to main. This job builds the Docker image, starts the container to verify it actually launches and responds to an HTTP request, and then pushes the verified image to GitHub Container Registry.

The build job authenticates using GITHUB_TOKEN, the same short-lived secret GitHub created automatically for the quality job. You do not create or store it anywhere: it is always available as secrets.GITHUB_TOKEN, and a job-specific packages: write permission allows this job to push to the registry without granting that permission to quality.

1. Add the build job to .github/workflows/ci.yml. Append these lines after the last line of the quality job block, at the same indentation level as quality: under jobs::

     build:
       needs: quality
       if: github.event_name == 'push' && github.ref == 'refs/heads/main'
       runs-on: ubuntu-latest
       permissions:
         contents: read
         packages: write
       steps:
         - uses: actions/checkout@v6
   
         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4
   
         - name: Log in to GitHub Container Registry
           uses: docker/login-action@v4
           with:
             registry: ghcr.io
             username: ${{ github.actor }}
             password: ${{ secrets.GITHUB_TOKEN }}
   
         - name: Normalize image name
           run: echo "IMAGE_NAME=ghcr.io/${GITHUB_REPOSITORY,,}:latest" >> "$GITHUB_ENV"
   
         - name: Build image
           uses: docker/build-push-action@v7
           with:
             context: .
             push: false
             load: true
             tags: app:smoke-test
             cache-from: type=gha
             cache-to: type=gha,mode=max
   
         - name: Smoke-test the container
           run: |
             docker run -d --name smoke -p 8080:8080 app:smoke-test
             for i in {1..10}; do
               if curl --fail --silent http://localhost:8080; then
                 break
               fi
               sleep 1
             done
             curl --fail http://localhost:8080
             docker stop smoke && docker rm smoke
   
         - name: Push to registry
           run: |
             docker tag app:smoke-test ${{ env.IMAGE_NAME }}
             docker push ${{ env.IMAGE_NAME }}

   needs: quality declares the dependency: build will not start until quality finishes successfully. If quality fails, build is skipped entirely and no runner time is spent on the image.

   The if: condition restricts build to pushes on main. Pull requests still run the quality job, giving reviewers fast feedback on linting and tests, but the build job is skipped until code actually lands on main. That keeps the registry clean and the workflow easier to read than putting the condition inside individual Docker steps.

   The Normalize image name step lowercases the GHCR tag. Container image names must be lowercase, so this avoids failures if the repository owner or name contains uppercase characters. In Bash, ${GITHUB_REPOSITORY,,} converts any uppercase letters to lowercase before writing the result to GITHUB_ENV, making it available to all later steps in the same job.

   The Build image step uses push: false and load: true. This builds the image and loads it into the runner’s local Docker daemon without pushing it anywhere. The Smoke-test the container step then starts that local image and retries the HTTP check for a few seconds while Flask finishes starting. The --fail flag makes curl exit with a nonzero code for any HTTP error response, which fails the step and skips the push. Only after the container passes does the final step send the verified image to GHCR.

2. Commit and push:

   git commit -am "Add Docker build, smoke test, and push job"
   git push

3. Open the new Actions run. The run page now shows two jobs: quality and build, with an arrow pointing from quality to build. Watch them in sequence: build stays queued until quality reports success, then starts immediately.

4. Expand the Smoke-test step inside the build job. You will see docker run start the container, followed by curl output showing the JSON response from your application:

   {"status":"ok","version":"1.0.0"}

   This is step 6 of the lecture’s feedback loop: you are verifying that the artifact you will actually deploy, the running container, behaves correctly, not just the source code that went into it.

5. Find your Docker image. After both jobs show green checkmarks, check your repository page on GitHub for a Packages section or open the package from your account’s Packages view if the sidebar has not updated yet. You should find cs312-ci-activity there, with the image tag, push timestamp, and your GitHub username as the owner.

6. Push a small change and watch the layer cache in action:

   # Edit app.py to change "1.0.0" to "1.0.1", then:
   git commit -am "Bump version"
   git push

   Open the new run’s build job and expand the Build image step. Layers that did not change (the base image and the pip installation layer) will appear as CACHED. Only the layer that copies app.py rebuilds. The Push to registry step sends only the changed layer to GHCR, not the entire image.

What is Docker Buildx?

Buildx is Docker’s extended build client, built on top of BuildKit. It replaces the classic docker build command with a plugin that understands advanced cache backends, including the type=gha backend used here, which stores Docker layer data in GitHub Actions’ own cache storage between runs. Without Buildx set up, the cache-from and cache-to lines in build-push-action would have no effect.

GITHUB_TOKEN vs Repository Secrets

GITHUB_TOKEN is generated automatically for each workflow run, scoped to the current repository, and expires when the job finishes. It requires no setup. Repository secrets (created in Settings > Secrets and variables > Actions) are for long-lived external credentials: API keys, SSH keys, cloud provider tokens. Use GITHUB_TOKEN whenever it is sufficient; reach for a named secret only when an external system requires it.

Think About It

The lecture says the container smoke test “catches a different class of bugs” than the pytest suite does. Look at the Dockerfile and think of one realistic mistake in it that pytest would never catch but the smoke test would catch immediately. What would the curl output look like when that mistake is present?

---

Testing Across Versions

A single Python version tells you the code works on 3.12. It does not tell you whether a teammate running 3.11 is about to hit a syntax difference or a compatibility edge case in a dependency. Rather than duplicating the quality job, you can ask GitHub Actions to generate one job per version automatically with a matrix strategy.

1. Update the quality job in .github/workflows/ci.yml to replace the hardcoded Python version with a matrix. Replace the entire quality: block with this version:

     quality:
       runs-on: ubuntu-latest
       strategy:
         matrix:
           python-version: ['3.11', '3.12']
         fail-fast: false
       steps:
         - uses: actions/checkout@v6
   
         - name: Set up Python
           uses: actions/setup-python@v6
           with:
             python-version: ${{ matrix.python-version }}
             cache: pip
   
         - name: Install dependencies
           run: pip install -r requirements.txt
   
         - name: Lint
           run: flake8 .
   
         - name: Test
           run: pytest -v

   The strategy.matrix block tells GitHub to run the quality job once for each value in python-version. The two jobs run in parallel on separate runners. The ${{ matrix.python-version }} expression in setup-python substitutes the current matrix value into that step, so each job installs the correct interpreter.

   Setting fail-fast: false tells GitHub to run all matrix combinations to completion even if one fails. With the default (fail-fast: true), a failure on 3.11 would cancel the 3.12 job before it finished, leaving you with an incomplete picture of which versions are broken.

2. Commit and push:

   git commit -am "Add matrix builds across Python 3.11 and 3.12"
   git push

3. Open the Actions run. The job list now shows two quality entries: quality (3.11) and quality (3.12). Both run in parallel on separate runners. The build job still shows a single arrow from quality, but it waits for both matrix instances to succeed before starting. When you declare needs: quality, GitHub waits for every matrix member of that job, not just the first one to finish.

4. Notice the job names in the run summary. GitHub labels each matrix job with its parameter values in parentheses. On a larger matrix, such as four Python versions across two operating systems, you would see eight labeled boxes. Any single failure is immediately identifiable by name without opening a log.

Think About It

With fail-fast: false, both matrix jobs run to completion even when one fails. When would fail-fast: true be the better choice? Think about a situation where seeing the first failure gives you enough information and running the rest of the matrix only burns runner minutes you have already paid for.

---

Saving Test Results

The pytest output scrolls past in the log and disappears when the runner is torn down. If a test fails in a run from last Tuesday, you want to know which specific assertion failed and what value it received, not just that the job was red. Artifacts let you attach files to a workflow run so they are downloadable long after the log has scrolled away.

You will add two things to the quality job: a JUnit XML report from pytest, and an upload step that saves it even when the tests fail, since that is exactly when you need the report most.

1. Update the Test step inside the quality job to emit an XML report alongside the normal output:

         - name: Test
           run: pytest -v --junitxml=pytest-report.xml

2. Add an upload step at the end of the quality job’s steps: list, after the Test step:

         - name: Upload test report
           if: always()
           uses: actions/upload-artifact@v7
           with:
             name: pytest-report-${{ matrix.python-version }}
             path: pytest-report.xml
             retention-days: 7
             if-no-files-found: error

   if: always() runs this step even if the Test step above it failed. Without it, a failing test would halt the job before reaching the upload step, and the report would be lost precisely when you need it most. The artifact name includes ${{ matrix.python-version }} so the two parallel matrix jobs do not conflict by uploading files with the same name. if-no-files-found: error also catches the different failure mode where pytest crashes before it writes the XML file at all.

3. Commit and push:

   git commit -am "Emit JUnit report and upload as artifact"
   git push

4. Open the completed run in the Actions tab. Scroll to the bottom of the run summary page. You will see an Artifacts section listing pytest-report-3.11 and pytest-report-3.12. Click either entry to download a zip file containing pytest-report.xml. Open the file: it is standard JUnit XML, readable by any CI dashboard, test analytics tool, or IDE that understands test results.

Artifacts vs Cache

Artifacts and the cache serve different purposes. A cache is a shortcut: it skips work by reusing outputs from a previous run. An artifact is a deliverable: it persists a file produced by the pipeline so you or a downstream job can use it. Both count against your GitHub storage quota, but a cache entry is evicted automatically after seven days without access, while an artifact survives until its retention period expires.

---

Let the Pipeline Protect You

The pipeline’s real value appears when something goes wrong. You will introduce a lint error and watch the pipeline block it before a single Docker layer is built.

1. Introduce a lint error. Open app.py and add an unused import at the top:

   import os
   from flask import Flask, jsonify

2. Commit and push:

   git commit -am "Oops: add unused import"
   git push

3. Open the Actions tab. Both quality (3.11) and quality (3.12) jobs will fail. Click into either run and expand the Lint step. You will see output like:

   ./app.py:1:1: F401 'os' imported but unused

   flake8 reports the file, line, column, and error code. The build job shows Skipped because needs: quality never allowed it to start. The pipeline did not pull any Docker base image, run Buildx, or spend any runner time on the build at all. The lint check, the cheapest step in the pipeline, stopped everything before the expensive work began.

4. Fix the file. Remove import os, leaving only the original two lines:

   from flask import Flask, jsonify

5. Commit and push the fix:

   git commit -am "Remove unused import"
   git push

6. Wait for the run to finish. All quality jobs and the build job should show green checkmarks. If GitHub has linked the package to the repository UI already, the Packages section in the sidebar will show a fresh push timestamp. If not, open the package from your account’s Packages view and confirm the owner, push timestamp, and latest tag there.

Re-Running Without a New Commit

If a step fails for a transient reason (a network timeout, a base image pull failing), click Re-run jobs > Re-run failed jobs at the top right of the run page. A real code error re-fails every time; a transient infrastructure issue usually passes on the second attempt. This is how you distinguish flaky failures from genuine bugs without cluttering the commit history.

---

Going Further

You have built the full feedback loop from the lecture: lint, test across Python versions, build an image, smoke-test the running container, upload a test report, and push the verified image to a registry. Two extensions move this pipeline closer to what production setups actually look like.

Add concurrency control to the build job. Right now, if you push two commits to main within thirty seconds, two build jobs can race each other. Add a concurrency block to the build job to prevent this:

  build:
    needs: quality
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    concurrency:
      group: build-main
      cancel-in-progress: false
    runs-on: ubuntu-latest
    ...

With cancel-in-progress: false, GitHub allows the currently running build to finish and queues at most one additional run. Any further runs that arrive while one is queued replace the queued entry, so only the latest pending commit survives. Push three commits in quick succession and watch the run list: the middle run is cancelled before it reaches the build job.

Push to Amazon ECR using OIDC instead of GHCR. GHCR is convenient because it is built into GitHub and requires no external credentials. ECR is what most production systems running on AWS use. The modern pattern is OIDC: AWS trusts GitHub’s identity provider, and the workflow exchanges a short-lived GitHub-issued token for temporary IAM credentials that expire when the job finishes.