{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"github-actions-ci","title":"GitHub Actions: the tests run on a machine that is not yours, before anything ships","url":"https://addaly.com/learn/python-for-ai/github-actions-ci","position":89,"of":89,"minutes":9,"answer":"A workflow file runs your tests on a clean machine on every push, which catches the dependency you forgot to pin and the file whose case only Windows and Linux care about.","keyIdea":"A workflow file runs your tests on a clean machine on every push, which catches the dependency you forgot to pin and the file whose case only Windows and Linux care about; secrets go in the repository settings and the paid-API tests stay behind a flag so a pull request from a stranger cannot spend your money."},"body":{"format":"markdown","text":"## Works on my machine\n\nEvery test passing on your laptop proves the code works with your Python, your installed packages, your environment variables, your filesystem and the files you forgot to commit. A second machine with none of those proves the code works. Continuous integration is the habit of having that second machine run the tests on every change, automatically, before the change is merged. GitHub Actions provides the machine for free for public repositories and with a generous monthly allowance for private ones.\n\n## The workflow file\n\n```yaml\n# .github/workflows/test.yml\nname: test\n\non:\n  push:\n  pull_request:\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        python-version: [\"3.11\", \"3.12\"]\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v5\n        with:\n          python-version: ${{ matrix.python-version }}\n          cache: pip\n      - run: pip install -e \".[dev]\"\n      - run: pyright src/\n      - run: pytest -q\n```\n\nRead it top to bottom. `on:` says when: every push and every pull request. `runs-on:` picks a fresh Ubuntu virtual machine. `matrix:` runs the job once per listed Python version, in parallel. The `steps` are what you would type: check out the code, install Python, install the package with its dev extras from module 7's `pyproject.toml`, run the type checker, run the tests. If any step exits non-zero, the job fails and the commit gets a red cross.\n\nCommit the file, push, and open the **Actions** tab. The first run takes a couple of minutes; with `cache: pip` the later ones are faster.\n\n## What it catches that you did not\n\nThe clean machine has no memory of your setup, and that is its value.\n\n**A dependency you use but never declared.** It was installed in your venv from some earlier experiment. On the runner, `ModuleNotFoundError`. The fix is in `pyproject.toml`, where it should have been.\n\n**A file that is not committed.** A test fixture, a prompt template, a `.env.example` you meant to add. The runner has only what git has.\n\n**Case.** macOS and Windows filesystems ignore letter case; Linux does not. `Path(\"Data/notes.md\")` can open `data/notes.md` on a typical case-insensitive Mac filesystem and fail on the Linux runner. Python normally checks the case of module names on both platforms, so `import tagger.Utils` requires the matching file name. A case-only rename can leave Git recording the old spelling: the Mac may have `Utils.py` while the repository and runner retain `utils.py`. Use `git mv`, through a temporary name if needed, and verify the staged rename with `git diff --cached`. The Linux runner is the only place many developers ever discover this.\n\n> Figure: What happens on a machine that has never seen your project. Timeline: You push, GitHub starts a fresh Ubuntu machine with none of your setup on it.; 0:10, Checkout brings only what git has. The fixture you never committed is not there.; 0:25, pip install from your declared dependencies. The package left over in your venv fails here.; 1:05, pytest runs on 3.11 and 3.12 at once, so syntax that arrived in 3.12 fails before a user meets it.; 1:40, import tagger.Utils, fine on a Mac, fails on Linux, where case matters.; Result, Green, or a locked door: with the branch protected, the pull request cannot merge red.. Every one of these is a bug that passes on your laptop. The runner's value is precisely that it remembers nothing about you: it has only what git has, in the Python you declared, on a filesystem where filenames have case. Protect the branch and a red cross stops being a suggestion.\n\n**Line endings and encodings.** A file saved with Windows line endings, a test that opens a file without `encoding=\"utf-8\"` and relies on the Mac's default. Module 5 warned; the runner enforces.\n\n**A different Python.** A syntax that arrived in 3.12 fails on 3.11 in the matrix, before a user on 3.11 finds it.\n\n## Secrets and the tests that cost money\n\nModule 4 split tests into two layers: fast tests with a fake provider, and a few slow ones against the real service. The fast ones run on every push. The real ones need the API key, and the key must not be in the repository.\n\nIn the repository's **Settings → Secrets and variables → Actions**, add `OPENAI_API_KEY`. In the workflow:\n\n```yaml\n      - run: pytest -q -m \"live\"\n        if: github.event_name == 'push' && github.ref == 'refs/heads/main'\n        env:\n          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n```\n\nThe secret is injected as an environment variable, and GitHub masks it in logs. The `if:` restricts the live tests to pushes on `main`, and here is the reason that matters: a pull request from a fork runs your workflow with the fork's code. If the live tests ran on pull requests with your secret available, a stranger could open a pull request whose \"test\" prints the key or spends the budget. GitHub withholds secrets from fork pull requests by default; the `if:` makes the intent explicit and keeps the paid tests off every branch push as well. Add a spend cap on the provider side regardless.\n\nMark the live tests with `@pytest.mark.live`, register the marker in `pyproject.toml`, and add `addopts = \"-m 'not live'\"` under `[tool.pytest.ini_options]` there, so `pytest -q` alone runs only the free ones. Registering only silences the unknown-marker warning; the `-m \"live\"` in the live step overrides `addopts`.\n\n## A schedule, for free\n\n```yaml\non:\n  schedule:\n    - cron: \"0 2 * * *\"      # 02:00 UTC daily\n  workflow_dispatch:         # and a button to run it by hand\n```\n\nThe same cron syntax as the previous lesson, running on GitHub's machine: a job that runs while your laptop is closed, with no server of your own. Times are UTC. Scheduled runs on free plans can be delayed under load and are paused on repositories with no activity for sixty days, so a critical job needs a heartbeat check as the previous lesson said.\n\n## Protecting the branch\n\nIn **Settings → Branches**, require the `test` job to pass before a pull request can merge. Now a red cross is not a suggestion; it is a locked door. For a project you work on alone this is discipline; for one with contributors it is the only thing standing between a well-meaning change and a broken `main`.\n\n## Reading a failure\n\nClick the red cross, open the failing step, and read the log from the bottom as module 4 taught for tracebacks. The environment section at the top of the log shows the Python version and the installed packages, which is where \"it passes locally\" gets resolved. To reproduce locally, `act` (free) runs workflow files on your own machine in Docker; more often, the log alone names the cause.\n\n## The habit\n\nEvery push runs the checks; every pull request shows them; nothing merges red. It is the last piece of the course: a program that installs from one file, is tested by a machine you do not control, keeps its secrets out of the code, and runs on a schedule with a lock and a done-record. That program you can hand to someone else, or to your future self, and it will still work.\n\n## Try this now\n\nAdd the workflow to your project and push. Read the first failure (there will be one), and fix it in the project, not the workflow. Then add the live-test step with the secret and the `if:`, open a pull request from a branch, and confirm the live step is skipped there and runs on `main`."},"check":{"question":"Tests pass on a developer's Mac. The same tests fail in GitHub Actions on `ubuntu-latest` with `ModuleNotFoundError: No module named 'tagger.Utils'`. The file was committed as `src/tagger/utils.py` and later renamed to `Utils.py` on the Mac. What does the CI machine know that the Mac did not?","options":[{"text":"Ubuntu requires an `__init__.py` in every folder, while macOS infers packages from the directory name.","correct":false,"tempting":"Both need `__init__.py` for a regular package; the module name is what differs here, not the package layout."},{"text":"GitHub Actions installs packages from `requirements.txt` in lowercase, renaming modules that contain capitals.","correct":false,"tempting":"pip does not rename modules; the file on disk is `utils.py` on both machines and only the lookup rules differ."},{"text":"The `src/` layout is not supported on Linux runners without a `setup.py`, so the package was never installed and Python fell back to importing from the working directory where the name differed.","correct":false,"tempting":"A `pyproject.toml` with the src layout installs identically on Linux; the error names a module inside a package that was found."},{"text":"Git may have retained the old spelling after the case-only rename on a case-insensitive filesystem. The Mac has `Utils.py`, while the repository and Linux runner retain `utils.py`. Record the rename with `git mv`, through a temporary name if needed, and verify `git diff --cached` before committing.","correct":true}]},"prev":{"slug":"scheduling-and-idempotent-jobs","title":"Running it every morning: cron, a lock file, and a job that is safe to run twice","url":"https://addaly.com/learn/python-for-ai/scheduling-and-idempotent-jobs"},"next":null,"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'GitHub Actions: the tests run on a machine that is not yours, before anything ships', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/github-actions-ci (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"GitHub Actions: the tests run on a machine that is not yours, before anything ships","courseTitle":"Python, from Zero, for AI","module":{"index":9,"slug":"building-the-thing","title":"Building the thing: a small AI program, end to end"},"answer":null,"keyIdea":"A workflow file runs your tests on a clean machine on every push, which catches the dependency you forgot to pin and the file whose case only Windows and Linux care about; secrets go in the repository settings and the paid-API tests stay behind a flag so a pull request from a stranger cannot spend your money.","hero":{"kind":"figure","figure":{"t":"figure","label":"Figure","figure":{"caption":"Every one of these is a bug that passes on your laptop. The runner’s value is precisely that it remembers nothing about you: it has only what git has, in the Python you declared, on a filesystem where filenames have case. Protect the branch and a red cross stops being a suggestion.","events":[{"when":"You push","what":"GitHub starts a fresh Ubuntu machine with none of your setup on it."},{"when":"0:10","what":"Checkout brings only what git has. The fixture you never committed is not there."},{"when":"0:25","what":"pip install from your declared dependencies. The package left over in your venv fails here."},{"when":"1:05","what":"pytest runs on 3.11 and 3.12 at once, so syntax that arrived in 3.12 fails before a user meets it."},{"when":"1:40","what":"import tagger.Utils, fine on a Mac, fails on Linux, where case matters."},{"when":"Result","what":"Green, or a locked door: with the branch protected, the pull request cannot merge red."}],"title":"What happens on a machine that has never seen your project","type":"timeline"},"alt":"Figure: What happens on a machine that has never seen your project. Timeline: You push, GitHub starts a fresh Ubuntu machine with none of your setup on it.; 0:10, Checkout brings only what git has. The fixture you never committed is not there.; 0:25, pip install from your declared dependencies. The package left over in your venv fails here.; 1:05, pytest runs on 3.11 and 3.12 at once, so syntax that arrived in 3.12 fails before a user meets it.; 1:40, import tagger.Utils, fine on a Mac, fails on Linux, where case matters.; Result, Green, or a locked door: with the branch protected, the pull request cannot merge red.. Every one of these is a bug that passes on your laptop. The runner’s value is precisely that it remembers nothing about you: it has only what git has, in the Python you declared, on a filesystem where filenames have case. Protect the branch and a red cross stops being a suggestion."}},"blocks":[{"t":"h2","id":"works-on-my-machine","runs":[{"text":"Works on my machine"}]},{"t":"p","runs":[{"text":"Every test passing on your laptop proves the code works with your Python, your installed packages, your environment variables, your filesystem and the files you forgot to commit. A second machine with none of those proves the code works. Continuous integration is the habit of having that second machine run the tests on every change, automatically, before the change is merged. GitHub Actions provides the machine for free for public repositories and with a generous monthly allowance for private ones."}]},{"t":"h2","id":"the-workflow-file","runs":[{"text":"The workflow file"}]},{"t":"code","lang":"yaml","label":"YAML","text":"# .github/workflows/test.yml\nname: test\n\non:\n  push:\n  pull_request:\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        python-version: [\"3.11\", \"3.12\"]\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v5\n        with:\n          python-version: ${{ matrix.python-version }}\n          cache: pip\n      - run: pip install -e \".[dev]\"\n      - run: pyright src/\n      - run: pytest -q"},{"t":"p","runs":[{"text":"Read it top to bottom. "},{"text":"on:","code":true},{"text":" says when: every push and every pull request. "},{"text":"runs-on:","code":true},{"text":" picks a fresh Ubuntu virtual machine. "},{"text":"matrix:","code":true},{"text":" runs the job once per listed Python version, in parallel. The "},{"text":"steps","code":true},{"text":" are what you would type: check out the code, install Python, install the package with its dev extras from module 7’s "},{"text":"pyproject.toml","code":true},{"text":", run the type checker, run the tests. If any step exits non-zero, the job fails and the commit gets a red cross."}]},{"t":"p","runs":[{"text":"Commit the file, push, and open the "},{"text":"Actions","b":true},{"text":" tab. The first run takes a couple of minutes; with "},{"text":"cache: pip","code":true},{"text":" the later ones are faster."}]},{"t":"h2","id":"what-it-catches-that-you-did-not","runs":[{"text":"What it catches that you did not"}]},{"t":"p","runs":[{"text":"The clean machine has no memory of your setup, and that is its value."}]},{"t":"p","runs":[{"text":"A dependency you use but never declared.","b":true},{"text":" It was installed in your venv from some earlier experiment. On the runner, "},{"text":"ModuleNotFoundError","code":true},{"text":". The fix is in "},{"text":"pyproject.toml","code":true},{"text":", where it should have been."}]},{"t":"p","runs":[{"text":"A file that is not committed.","b":true},{"text":" A test fixture, a prompt template, a "},{"text":".env.example","code":true},{"text":" you meant to add. The runner has only what git has."}]},{"t":"p","runs":[{"text":"Case.","b":true},{"text":" macOS and Windows filesystems ignore letter case; Linux does not. "},{"text":"Path(\"Data/notes.md\")","code":true},{"text":" can open "},{"text":"data/notes.md","code":true},{"text":" on a typical case-insensitive Mac filesystem and fail on the Linux runner. Python normally checks the case of module names on both platforms, so "},{"text":"import tagger.Utils","code":true},{"text":" requires the matching file name. A case-only rename can leave Git recording the old spelling: the Mac may have "},{"text":"Utils.py","code":true},{"text":" while the repository and runner retain "},{"text":"utils.py","code":true},{"text":". Use "},{"text":"git mv","code":true},{"text":", through a temporary name if needed, and verify the staged rename with "},{"text":"git diff --cached","code":true},{"text":". The Linux runner is the only place many developers ever discover this."}]},{"t":"p","runs":[{"text":"Line endings and encodings.","b":true},{"text":" A file saved with Windows line endings, a test that opens a file without "},{"text":"encoding=\"utf-8\"","code":true},{"text":" and relies on the Mac’s default. Module 5 warned; the runner enforces."}]},{"t":"p","runs":[{"text":"A different Python.","b":true},{"text":" A syntax that arrived in 3.12 fails on 3.11 in the matrix, before a user on 3.11 finds it."}]},{"t":"h2","id":"secrets-and-the-tests-that-cost-money","runs":[{"text":"Secrets and the tests that cost money"}]},{"t":"p","runs":[{"text":"Module 4 split tests into two layers: fast tests with a fake provider, and a few slow ones against the real service. The fast ones run on every push. The real ones need the API key, and the key must not be in the repository."}]},{"t":"p","runs":[{"text":"In the repository’s "},{"text":"Settings → Secrets and variables → Actions","b":true},{"text":", add "},{"text":"OPENAI_API_KEY","code":true},{"text":". In the workflow:"}]},{"t":"code","lang":"yaml","label":"YAML","text":"      - run: pytest -q -m \"live\"\n        if: github.event_name == 'push' && github.ref == 'refs/heads/main'\n        env:\n          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}"},{"t":"p","runs":[{"text":"The secret is injected as an environment variable, and GitHub masks it in logs. The "},{"text":"if:","code":true},{"text":" restricts the live tests to pushes on "},{"text":"main","code":true},{"text":", and here is the reason that matters: a pull request from a fork runs your workflow with the fork’s code. If the live tests ran on pull requests with your secret available, a stranger could open a pull request whose “test” prints the key or spends the budget. GitHub withholds secrets from fork pull requests by default; the "},{"text":"if:","code":true},{"text":" makes the intent explicit and keeps the paid tests off every branch push as well. Add a spend cap on the provider side regardless."}]},{"t":"p","runs":[{"text":"Mark the live tests with "},{"text":"@pytest.mark.live","code":true},{"text":", register the marker in "},{"text":"pyproject.toml","code":true},{"text":", and add "},{"text":"addopts = \"-m 'not live'\"","code":true},{"text":" under "},{"text":"[tool.pytest.ini_options]","code":true},{"text":" there, so "},{"text":"pytest -q","code":true},{"text":" alone runs only the free ones. Registering only silences the unknown-marker warning; the "},{"text":"-m \"live\"","code":true},{"text":" in the live step overrides "},{"text":"addopts","code":true},{"text":"."}]},{"t":"h2","id":"a-schedule-for-free","runs":[{"text":"A schedule, for free"}]},{"t":"code","lang":"yaml","label":"YAML","text":"on:\n  schedule:\n    - cron: \"0 2 * * *\"      # 02:00 UTC daily\n  workflow_dispatch:         # and a button to run it by hand"},{"t":"p","runs":[{"text":"The same cron syntax as the previous lesson, running on GitHub’s machine: a job that runs while your laptop is closed, with no server of your own. Times are UTC. Scheduled runs on free plans can be delayed under load and are paused on repositories with no activity for sixty days, so a critical job needs a heartbeat check as the previous lesson said."}]},{"t":"h2","id":"protecting-the-branch","runs":[{"text":"Protecting the branch"}]},{"t":"p","runs":[{"text":"In "},{"text":"Settings → Branches","b":true},{"text":", require the "},{"text":"test","code":true},{"text":" job to pass before a pull request can merge. Now a red cross is not a suggestion; it is a locked door. For a project you work on alone this is discipline; for one with contributors it is the only thing standing between a well-meaning change and a broken "},{"text":"main","code":true},{"text":"."}]},{"t":"h2","id":"reading-a-failure","runs":[{"text":"Reading a failure"}]},{"t":"p","runs":[{"text":"Click the red cross, open the failing step, and read the log from the bottom as module 4 taught for tracebacks. The environment section at the top of the log shows the Python version and the installed packages, which is where “it passes locally” gets resolved. To reproduce locally, "},{"text":"act","code":true},{"text":" (free) runs workflow files on your own machine in Docker; more often, the log alone names the cause."}]},{"t":"h2","id":"the-habit","runs":[{"text":"The habit"}]},{"t":"p","runs":[{"text":"Every push runs the checks; every pull request shows them; nothing merges red. It is the last piece of the course: a program that installs from one file, is tested by a machine you do not control, keeps its secrets out of the code, and runs on a schedule with a lock and a done-record. That program you can hand to someone else, or to your future self, and it will still work."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Add the workflow to your project and push. Read the first failure (there will be one), and fix it in the project, not the workflow. Then add the live-test step with the secret and the "},{"text":"if:","code":true},{"text":", open a pull request from a branch, and confirm the live step is skipped there and runs on "},{"text":"main","code":true},{"text":"."}]}],"check":{"question":[{"text":"Tests pass on a developer’s Mac. The same tests fail in GitHub Actions on "},{"text":"ubuntu-latest","code":true},{"text":" with "},{"text":"ModuleNotFoundError: No module named 'tagger.Utils'","code":true},{"text":". The file was committed as "},{"text":"src/tagger/utils.py","code":true},{"text":" and later renamed to "},{"text":"Utils.py","code":true},{"text":" on the Mac. What does the CI machine know that the Mac did not?"}],"options":[{"text":[{"text":"Ubuntu requires an "},{"text":"__init__.py","code":true},{"text":" in every folder, while macOS infers packages from the directory name."}],"correct":false,"tempting":[{"text":"Both need "},{"text":"__init__.py","code":true},{"text":" for a regular package; the module name is what differs here, not the package layout."}]},{"text":[{"text":"GitHub Actions installs packages from "},{"text":"requirements.txt","code":true},{"text":" in lowercase, renaming modules that contain capitals."}],"correct":false,"tempting":[{"text":"pip does not rename modules; the file on disk is "},{"text":"utils.py","code":true},{"text":" on both machines and only the lookup rules differ."}]},{"text":[{"text":"The "},{"text":"src/","code":true},{"text":" layout is not supported on Linux runners without a "},{"text":"setup.py","code":true},{"text":", so the package was never installed and Python fell back to importing from the working directory where the name differed."}],"correct":false,"tempting":[{"text":"A "},{"text":"pyproject.toml","code":true},{"text":" with the src layout installs identically on Linux; the error names a module inside a package that was found."}]},{"text":[{"text":"Git may have retained the old spelling after the case-only rename on a case-insensitive filesystem. The Mac has "},{"text":"Utils.py","code":true},{"text":", while the repository and Linux runner retain "},{"text":"utils.py","code":true},{"text":". Record the rename with "},{"text":"git mv","code":true},{"text":", through a temporary name if needed, and verify "},{"text":"git diff --cached","code":true},{"text":" before committing."}],"correct":true,"tempting":null}],"order":[0,3,2,1],"why":null},"prev":{"slug":"scheduling-and-idempotent-jobs","title":"Running it every morning: cron, a lock file, and a job that is safe to run twice","minutes":9},"next":null}}