GitHub Actions Basics: CI on Every Push

Create the workflow directory and the file itself. The name is arbitrary, ci.yml is the usual convention, but the directory path is not: GitHub only discovers workflows under .github/workflows/ at the repository root.

CREATE THE WORKFLOW FILE

mkdir -p .github/workflows
touch .github/workflows/ci.yml

Start with the minimal version below. It already does the essential job: on every push and every pull request, check out the code, install Python 3.11 with pip caching enabled, install dependencies, and run the test suite.

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11', cache: 'pip' }
      - run: pip install -r requirements.txt
      - run: pytest -q

Walk through what each line means, because every workflow you will ever write is a variation on this shape:

• name: CI, the display name in the Actions tab and, importantly, the first half of the status check name that branch protection will reference in step 03.
• on: [push, pull_request], the triggers. push covers direct commits to any branch; pull_request covers proposed merges so the check runs on the merged result before anyone clicks the merge button.
• runs-on: ubuntu-latest, the runner image. GitHub-hosted runners are free for public repos and include generous monthly minutes for private ones.
• actions/checkout@v4, clones your repo onto the runner. Without this step the runner starts with an empty directory; forgetting it is a classic beginner bug that produces "No such file or directory" on the very next step.
• actions/setup-python@v5 with cache: 'pip', installs the requested Python version and caches the pip download cache keyed on a hash of requirements.txt. The first run populates the cache; later runs skip re-downloading every package.
• The two run: steps are plain shell. Any command you would type locally works here.

Once the minimal version is green, grow it into the two-job shape from the architecture diagram: lint and test run in parallel, and a failing linter stops bad style from reaching main just as surely as a failing test. The full file also pins the cache key explicitly so you can see how caching works under the hood.

FULL WORKFLOW, .github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Cancel superseded runs on the same branch to save runner minutes.
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      - run: pip install ruff
      - run: ruff check src tests

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest -q --cov=src --cov-report=term-missing

Notes on the additions: concurrency cancels the previous in-flight run when you push again to the same branch, handy when you spot a typo seconds after pushing. The push.branches filter keeps pushes to throwaway feature branches from burning minutes, while pull_request still validates every proposed merge into main. The two jobs have no needs: relationship, so GitHub schedules them in parallel.

How to verify: the file is just YAML, so a syntax error will break the whole workflow before it ever runs. Lint it locally before pushing:

VALIDATE THE YAML BEFORE COMMITTING

python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci.yml'))" && echo "YAML OK"
# or, better, use the purpose-built linter:
actionlint .github/workflows/ci.yml

actionlint goes beyond YAML syntax, it catches misspelled action inputs, unknown contexts like ${{ github.branhc }}, and shellcheck issues inside run: blocks. It is the single highest-value tool for workflow debugging.

Common mistake: YAML is whitespace-sensitive, and mixing tabs with spaces produces errors like mapping values are not allowed here. Configure your editor to insert two spaces for .yml files. A subtler gotcha: some YAML 1.1 parsers (including Python's yaml.safe_load) read the bare key on: as the boolean True, GitHub parses it correctly, but do not be alarmed if a generic YAML tool shows the key as true.

Commit the workflow file and push it. Because the trigger list includes push, this very push is also the workflow's first run, a satisfying feedback loop.

COMMIT AND PUSH THE WORKFLOW

git add .github/workflows/ci.yml
git commit -m "Add CI workflow: lint + test on push and PR"
git push origin main

Then watch the run live from the terminal. gh run watch attaches to the most recent run and streams each job's status until it completes; --exit-status makes the command itself fail if the run fails, which is useful in scripts.

A full two-job run looks like this in the terminal:

Notice the run time: the first run is the slow one because it populates the pip cache. Push a trivial change (edit a comment, amend, push again) and compare, the setup-python step should now log a cache hit:

When a run goes red, do not click around the web UI hunting for the failure, pull the failing logs straight into your terminal:

READ ONLY THE FAILED STEPS OF A RUN

gh run list --limit 5
gh run view --log-failed          # logs from failed steps of the latest run
gh run view --job 40567891887 --log  # full log of a specific job (job IDs need --job)

How to verify: after the push, the commit on GitHub should carry a green check (or yellow dot while running). Clicking it shows both jobs. In the Actions tab, the run appears under the workflow name "CI" with the commit message as its title.

Common mistake: committing the file but forgetting git add .github/workflows/ci.yml (the directory is easy to overlook because it is hidden), or pushing to a feature branch while push.branches filters to [main], in both cases the Actions tab stays empty and it looks like Actions is broken. Check git status and your trigger filters first.

A workflow that only reports failures is advisory; developers can ignore it and merge anyway. Branch protection turns the status check into a gate: until the checks named in the rule pass on the exact commit being merged, GitHub disables the merge button. You can configure this in the UI under Settings › Branches › Add branch ruleset, but doing it with the API is repeatable and reviewable.

Set the workflow as a required status check in branch protection so failing code cannot merge.

Note: the protection API accepts only the complete required_status_checks object in one PUT, so the reliable form is the full JSON payload below. A partial update that sets only strict without the contexts array fails validation.

The :owner and :repo placeholders are filled in automatically by gh from your git remote. strict=true means the PR branch must also be up to date with main before merging, the strictest and safest mode, since the check then ran against exactly what will land on main.

Strict mode alone does not name which checks are required. Name them explicitly so the gate waits for your two jobs. The check names follow the pattern workflow name / job name, here, lint and test as jobs inside the CI workflow:

REQUIRE BOTH JOBS AS NAMED STATUS CHECKS

gh api repos/:owner/:repo/branches/main/protection -X PUT \
  --input - <<'EOF'
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["lint", "test"]
  },
  "enforce_admins": true,
  "required_pull_request_reviews": null,
  "restrictions": null
}
EOF

That GET call is your verification: it confirms the rule stuck and lists exactly which contexts GitHub will wait for. enforce_admins: true is deliberate, without it, repository admins can merge over a red check, which is how "temporary" exceptions become permanent holes.

Common mistake: a context name that does not match any real check. If you require CI / test but the job is named test, the PR waits forever on a check that will never report. The context must match the job name (or workflow / job for reusable workflows). The check must also have run at least once before GitHub will offer it in the branch-protection search box, one more reason step 02 comes first.

The minimal on: [push, pull_request] covers active development, but two more trigger shapes earn their keep quickly: a schedule that runs CI even when nobody is pushing (this catches "dependency rot", a passing suite that starts failing because a transitive dependency or a GitHub runner image changed), and path filters that skip CI for changes that cannot break code, like edits to documentation.

Replace the on: block of ci.yml with this expanded version:

TRIGGERS, PUSH, PR, SCHEDULE, MANUAL, WITH PATH FILTERS

on:
  push:
    branches: [main]
    paths-ignore:
      - '**.md'
      - 'docs/**'
  pull_request:
    branches: [main]
  schedule:
    # 03:17 UTC every Monday, cron is always UTC on GitHub.
    - cron: '17 3 * * 1'
  workflow_dispatch: {}   # adds a "Run workflow" button in the Actions tab

Each key does one thing: paths-ignore skips the run when every changed file matches the ignore list; schedule takes standard five-field cron expressions (minute, hour, day-of-month, month, day-of-week) in UTC; workflow_dispatch enables manual runs from the web UI or gh workflow run ci.yml, which is invaluable when debugging the workflow itself.

How to verify: after pushing, run gh workflow list to confirm the workflow is active, then trigger a manual run and confirm it appears:

LIST WORKFLOWS AND TRIGGER ONE MANUALLY

gh workflow list
gh workflow run ci.yml
gh run list --workflow=ci.yml --limit 3

For the schedule, you do not need to wait until Monday: confirm the cron expression parses the way you think with a tool like crontab.guru, and check that the workflow file containing it is on the default branch, schedules are read from the default branch only.

Common mistake: editing the schedule trigger on a feature branch and wondering why nothing runs at the appointed time. Scheduled runs only use the workflow as it exists on the default branch. Two related gotchas: GitHub delays scheduled runs during high-load periods (a 03:17 cron may start at 03:40), and GitHub disables schedules entirely on repos with no activity for 60 days.

Code that passes on Python 3.11 can still break on 3.10 (a typing feature) or 3.12 (a removed stdlib API). A matrix turns one job definition into N parallel jobs, one per combination of the variables you list. Replace the test job with this matrix version:

MATRIX BUILD, OS × PYTHON VERSION

  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false   # let every combination finish even if one fails
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest -q

This single job block produces 3 × 2 = 6 parallel jobs. fail-fast: false matters: the default is true, which cancels the other five jobs the moment one fails, convenient for saving minutes, but it hides whether a failure is version-specific or universal, which is exactly what you want to know from a matrix.

How to verify: push and watch the run. You should see six jobs, each named from the matrix values:

That sample output also shows the matrix doing its job: a failure isolated to one OS-and-version cell points at a platform-specific bug, not a general regression.

Common mistake: the matrix changes the status check names, they become test (3.10, ubuntu-latest) and so on. The branch protection rule from step 03 that requires test will now wait forever, because no check named exactly test exists anymore. Fix it by updating the required contexts to each matrix combination, or by adding a single test-result job with needs: test and if: always() that fails unless needs.test.result == 'success', and requiring only that one aggregator check. The aggregator pattern scales much better as the matrix grows.

Build and deploy steps need credentials, an API token, a registry password, an SSH key. Secrets are stored encrypted in the repo (or organization), injected into the workflow at runtime, and masked in logs. Create one with the CLI so the value never appears in your shell history as plain text:

CREATE A REPOSITORY SECRET

gh secret set DEPLOY_TOKEN
# (paste the token at the prompt, press Enter)
gh secret list

Note what the listing shows: the name and the update date, never the value. There is no read-back API, if you lose the value, you rotate it, which is the correct security posture.

Next, create an environment. Environments are named deployment targets (staging, production) that can carry their own secrets and, crucially, protection rules such as required reviewers, a human must approve before a job touching production starts. Create it in the UI under Settings › Environments › New environment, name it production, and optionally add yourself as a required reviewer. Reference both in the workflow:

USING A SECRET AND AN ENVIRONMENT IN A JOB

  deploy:
    needs: [lint, test]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: ./scripts/deploy.sh

Two details worth reading twice: the secret is passed through env: rather than written inline in the run: script (inline values can leak via process listing and error messages), and the if: condition restricts deploys to pushes on main, without it, every pull request would attempt a production deploy.

Common mistake: assuming secrets are available in every context. Workflows triggered by pull requests from forks receive no secrets at all (a deliberate defense against a malicious PR exfiltrating them), so a deploy step on a forked PR fails with an empty credential. Also note that log masking is literal string matching: if your token is very short or its value is a common substring, masking becomes unreliable, prefer long, randomly generated tokens.

Remember that every job gets a fresh, empty runner, files created in the test job do not exist in a later deploy job. The bridge between jobs is an artifact: a named bundle of files uploaded at the end of one job and downloaded at the start of another. Add a build job that packages the application and hands the package downstream:

BUILD JOB WITH ARTIFACT UPLOAD

  build:
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Build the package
        run: |
          pip install build
          python -m build
      - uses: actions/upload-artifact@v4
        with:
          name: dist-package
          path: dist/
          retention-days: 7

needs: [lint, test] is the sequencing mechanism: build waits until both upstream jobs succeed, and is skipped entirely if either fails, no point packaging broken code. retention-days: 7 keeps storage costs down; the default is much longer.

The deploy job from step 06 then pulls exactly the bits that were built and tested, instead of rebuilding them:

DOWNLOAD THE ARTIFACT IN THE DEPLOY JOB

      - uses: actions/download-artifact@v4
        with:
          name: dist-package
          path: dist/
      - run: ls -lh dist/    # the exact package from the build job is here

How to verify: open the run summary in the Actions tab, a "Artifacts" section lists dist-package with its size and expiry date. From the terminal, gh run view shows the same list, and you can pull the artifact down locally to inspect what would have been deployed:

DOWNLOAD AN ARTIFACT LOCALLY FOR INSPECTION

gh run download --name dist-package --dir ./artifact-check
ls ./artifact-check

Common mistake: treating artifacts as shared storage between runs or workflows. An artifact belongs to the run that created it; another workflow, or a re-run a week later after retention expired, cannot fetch it by name alone. If you need durable outputs, publish to a real package registry or a release, and keep artifacts for short-lived hand-offs inside one run.

The final pipeline shape chains everything: lint and test in parallel, then build, then deploy, each stage gated by the previous one through needs:. Update the deploy job so it runs after build (not just after lint and test) and downloads the artifact as shown in step 07:

FINAL JOB CHAIN, LINT + TEST → BUILD → DEPLOY

  deploy:
    needs: [build]   # build already needs [lint, test], so this transitively gates on all three
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist-package, path: dist/ }
      - name: Deploy
        env: { DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} }
        run: ./scripts/deploy.sh dist/

Because needs is transitive, requiring build is enough: build itself required lint and test, so deploy can never start on unverified code. In the Actions UI the run renders as a left-to-right graph of these dependencies.

Last, make the pipeline's health visible without opening the Actions tab: every workflow exposes a badge SVG. Add it to the top of your README.md:

STATUS BADGE FOR README.md

![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg?branch=main)

Replace OWNER/REPO with your repository slug. The ?branch=main query keeps the badge pinned to the default branch so a red feature-branch experiment does not make the project look broken.

How to verify: paste the badge URL into a browser, it should return an SVG reading "CI | passing" once the latest run on main is green. For the deploy gating, push to a feature branch and confirm in the Actions tab that the deploy job is skipped, then merge to main and confirm it runs (and pauses for approval if you configured required reviewers on the production environment).

Common mistake: putting the badge in a private repo's README and getting a broken image, badge SVGs for private repos require authentication. Also common: a deploy step that "succeeds" while doing nothing because deploy.sh exits 0 on every path. Make the script fail loudly (set -euo pipefail in bash) and verify a real post-deploy signal, a health-check endpoint, a version endpoint, a log line on the server, rather than trusting the green checkmark alone.