How to set up GitHub Actions CI pipelines with testing, caching, and branch protection

From theory to a green checkmark You know what a pipeline does, now let's build one. By the end of this article you'll have a working CI pipeline that runs on every push and every pull request, installs your dependencies, lints your code, runs your tests, and shows a green checkmark (or a red X) right in the GitHub UI. It's free, it ships with every GitHub repo, and you can have it running in ten minutes. We'll build it up one piece at a time so nothing is a black box. Each code block is a real, working .github/workflows/*.yml file, copy them straight into a repo. Note: Who this is for: Anyone with a GitHub repo and basic Git who's never written a workflow file. The examples use a Node.js project (npm), but the structure is identical for Python, Go, or anything else, only the install/test commands change. If you've read CI/CD Fundamentals, you have all the background you need. The vocabulary you need (just five words) GitHub Actions has its own nouns. Learn these five and the YAML stops looking cryptic. They nest inside each other like Russian dolls. Term What it is Workflow One .yml file in .github/workflows/. The whole automated process. Event What triggers the workflow, a push, a pull_request, a schedule. Job A group of steps that run together on one machine. Jobs can run in parallel. Step A single task in a job, run a command, or use a prebuilt action. Runner The machine a job runs on, e.g. ubuntu-latest, fresh every run. The five building blocks, biggest to smallest. Put together: a workflow listens for an event, which kicks off one or more jobs, each running its steps on a runner. That's the entire model. Step 1, the smallest workflow that does something Create the file .github/workflows/ci.yml in your repo. The folder path matters exactly, GitHub only looks in .github/workflows/. Start with the absolute minimum: check out the code and print a line. .github/workflows/ci.yml name: CI # shows up in the Actions tab on: [push, pull_request] # the events that trigger it jobs: hello: # job id (any name) runs-on: ubuntu-latest # the runner steps: - uses: actions/checkout@v4 # pull your repo onto the runner - run: echo "Pipeline is alive!" Commit and push it. Open the Actions tab on GitHub and you'll see the run executing live. That's a working pipeline, it just doesn't do anything useful yet. Two things worth understanding now: actions/checkout@v4 is a prebuilt action (someone else's reusable step) that clones your repo onto the runner, and run: executes a shell command. Almost every step is one of those two shapes. Tip: YAML is whitespace-sensitive, indentation is two spaces, never tabs. About half of all "my workflow won't run" problems are an indentation slip. If GitHub shows a syntax error, check your spacing first. Step 2, install, lint, and test Now make it real. We'll set up Node, do a clean dependency install, lint, and run tests, the three checks that should gate every change. Each is just another step. .github/workflows/ci.yml name: CI on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Node uses: actions/setup-node@v4 with: node-version: "20" - name: Install dependencies run: npm ci # clean install from the lockfile - name: Lint run: npm run lint - name: Run tests run: npm test A few deliberate choices here. We use npm ci, not npm install, ci installs the exact versions from your lockfile and fails if the lockfile is out of sync, which is precisely what you want in automation: reproducible, no surprises. We also narrowed the push trigger to the main branch while keeping pull_request open, so the pipeline runs on every PR and on merges to main, but not on every push to every random feature branch (saving CI minutes). Warning: In CI, prefer npm ci over npm install. npm install can quietly update your lockfile and pull different versions than your teammates have, defeating the whole point of a reproducible build. npm ci is stricter and faster. (Python: use pip install -r requirements.txt with pinned versions; the principle is the same.) Step 3, make it fast with caching Right now every run re-downloads all your dependencies from scratch, slow and wasteful. Caching stores them between runs so repeat builds are dramatically faster. The setup-node action has caching built in; you just turn it on. .github/workflows/ci.yml (excerpt) - name: Set up Node uses: actions/setup-node@v4 with: node-version: "20" cache: "npm" # cache ~/.npm keyed on your lockfile That single cache: "npm" line keys the cache on your package-lock.json. As long as your dependencies don't change, the cache is reused and npm ci finishes in seconds instead of minutes. When you add or update a package, the lockfile changes, the key changes, and the cache rebuilds automatically. You never manage it by hand. Tip: Slow pipelines get ignored. If CI takes longer than your coffee refill, people stop watching it and start merging on faith, which defeats the purpose. Caching is the single highest-leverage speedup for most pipelines. Turn it on early. Step 4, run independent jobs in parallel Linting and testing don't depend on each other, so why run them one after the other? Split them into separate jobs and GitHub runs them on separate machines simultaneously, your total wall-clock time drops to whichever is slowest, not the sum. .github/workflows/ci.yml name: CI on: push: branches: [main] pull_request: jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: "20", cache: "npm" } - run: npm ci - run: npm run lint test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: "20", cache: "npm" } - run: npm ci - run: npm test Now lint and test run in parallel. Each job is fully isolated, a fresh runner with nothing shared, which is why each repeats the checkout and install. That isolation is a feature: one job can't pollute another. If you ever need a job to wait for another (say, deploy after tests pass), you add needs: test to it, and GitHub sequences them for you. Step 5, make the pipeline a required status check A green checkmark is nice, but the real power move is making it mandatory: configure your repo so a pull request cannot be merged until CI passes. This turns your pipeline from a suggestion into a gate that protects main. Open branch protection: In your GitHub repo: Settings → Branches → Add branch protection rule. Set the branch name pattern to main. Require status checks: Tick "Require status checks to pass before merging," then search for and select your jobs (lint and test) from the list. They appear once they've run at least once. Require a PR: Also tick "Require a pull request before merging" so nobody can push straight to main and skip the checks entirely. Save and test it: Open a PR that deliberately breaks a test. GitHub now blocks the Merge button until the pipeline is green. That's CI doing its actual job. Warning: Without branch protection, CI is advisory, a teammate in a hurry can merge a red build. The status check is what makes the pipeline enforced. Set it up the moment your CI is stable; it's the difference between "we have tests" and "broken code can't reach main." Common mistakes that cost hours Wrong file location. Workflows only run from .github/workflows/. A file in .github/ or workflows/ is silently ignored, no error, just nothing happens. Tabs instead of spaces. YAML demands spaces. A single tab anywhere breaks the whole file. Configure your editor to show whitespace. Using npm install instead of npm ci. install can drift your lockfile and produce non-reproducible builds. ci is the automation-correct choice. Hardcoding secrets in the YAML. Tokens and passwords in a workflow file land in your Git history permanently. Use repo Settings → Secrets and reference them as ${{ secrets.NAME }}. Never enabling branch protection. A pipeline that doesn't block merges is decoration. Make it a required status check or broken code will still reach main. Forgetting the cache. Skipping cache: "npm" makes every run re-download everything. People then stop waiting for slow CI, and a CI nobody watches is worthless. Takeaways Your first pipeline in seven lines A workflow lives in .github/workflows/*.yml and is triggered by events. Workflow → jobs → steps → runners. Jobs run in parallel by default. Use actions/checkout to get your code, actions/setup-node to set up the toolchain. Use npm ci (not install) for reproducible builds; add cache: "npm" for speed. Split independent work (lint, test) into separate jobs to run them in parallel. Use needs: to sequence jobs when one must wait for another. Enable branch protection with required status checks so red builds can't merge. Where to go next You have CI gating every change. The natural next steps are understanding the bigger picture you just plugged into, practicing the commands hands-on, and adding a build step that packages your app into a container. CI/CD Fundamentals, the full mental model your pipeline fits into. Practice in the CI/CD lab, run real pipeline commands in an in-browser terminal. Dockerfile Best Practices, package your app into a small, fast, secure image to deploy from CI. Originally published on TheSimplifiedTech, where this guide is interactive, with in-browser terminal labs and diagrams. Learn cloud and DevOps by doing, no videos.

Estimated reading time: ~6 minutes. No prior experience required. The Friday deploy that ruined a weekend There was a ritual I do not miss: the manual deploy. Someone would pull the latest code onto a server by hand, run a few commands from memory, cross their fingers, and hope. One Friday, a teammate forgot a single step. The code went live with a broken setting, nobody ran the tests first, and we spent Saturday untangling it. The lesson wasn't "be more careful." Humans forget steps, that's what humans do. The lesson was that the repetitive, error-prone work of testing and shipping code should be done by a robot, the same way, every single time. That robot is called CI/CD, and GitHub Actions is one of the most popular ways to build one. By the end of this post you'll understand what CI/CD is, what GitHub Actions is, the core concepts, how a pipeline is built, the traps, and how AI helps. What is CI/CD, really? Two ideas hiding behind two scary letters each: CI, Continuous Integration: every time someone changes the code, automatically build it and run the tests. Catch problems the moment they're introduced, not weeks later. CD, Continuous Delivery/Deployment: once the code passes all checks, automatically package and ship it to where it runs. One sentence: CI/CD is an automated assembly line that takes your code from "just changed" to "tested and deployed" without a human doing the repetitive steps by hand. GitHub Actions is a tool built into GitHub that runs this assembly line whenever something happens in your repository, like someone pushing code. The assembly line analogy Think of a car factory. Nobody bolts a car together from memory on the floor, hoping they didn't skip the brakes. There's an assembly line: each station does one job in a fixed order, quality checks happen automatically, and a car only rolls out the door if it passed every station. GitHub Actions is that assembly line for your code. Push a change, and the line starts: install dependencies → run tests → check quality → build → deploy. If any station fails, the line stops and tells you, before the broken car reaches a customer. The core concepts GitHub Actions has a small vocabulary. Learn these five. 1. Workflow A workflow is the whole assembly line, a file describing what should happen automatically. It lives in your repo under .github/workflows/ as a YAML file. You can have several (one for testing, one for deploying). 2. Event (trigger) An event is what starts the workflow. The most common is "someone pushed code" or "someone opened a pull request," but it can also be a schedule ("every night at 2 a.m.") or a manual button click. 3. Job A job is a group of steps that run together on a fresh machine. A workflow can have multiple jobs, maybe a "test" job and a "deploy" job, that run in order or in parallel. 4. Step and action A step is a single instruction in a job ("install Python," "run the tests"). An action is a reusable, pre-built step someone already wrote that you just plug in, like "check out my code" or "set up Node.js." (This is where the name comes from.) You snap together prebuilt actions instead of scripting everything. 5. Runner A runner is the machine that actually executes the job. GitHub provides fresh, clean runners in the cloud, so your pipeline runs in a pristine environment every time, no "works on my machine" leftovers. flowchart LR E[Event: push code] --> W[Workflow starts] W --> J1[Job: Test] J1 --> S1[Step: checkout code] S1 --> S2[Step: install deps] S2 --> S3[Step: run tests] J1 -->|passed| J2[Job: Deploy] J1 -->|failed| STOP[Stop + notify] Let's actually build one Here's a complete, minimal workflow that runs tests every time someone pushes code or opens a pull request. Save it as .github/workflows/test.yml. name: Run Tests # WHEN this should run. on: push: branches: [main] pull_request: jobs: test: # one job called "test" runs-on: ubuntu-latest # run on a fresh Linux machine steps: - name: Check out the code uses: actions/checkout@v4 # a prebuilt action - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install dependencies run: pip install -r requirements.txt - name: Run the tests run: pytest The moment this file is in your repo, GitHub starts running your tests on every change, automatically, on a clean machine, with a green check or red X shown right on the pull request. No one can merge broken code without seeing it fail first. That Friday disaster becomes structurally impossible. Adding a deploy step A second job can deploy only if the tests passed: deploy: needs: test # only runs if "test" succeeded runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Deploy run: ./deploy.sh env: API_TOKEN: ${{ secrets.API_TOKEN }} # from GitHub Secrets, never in code Notice needs: test, the deploy station only runs if the test station passed. And the token comes from GitHub Secrets, a safe vault, never hard-coded. A realistic pipeline A typical project's assembly line looks like this: flowchart LR A[Push / Pull Request] --> B[Install dependencies] B --> C[Run tests] C --> D[Check code style / lint] D --> E[Build the package or image] E --> F{On main branch?} F -->|yes| G[Deploy to production] F -->|no| H[Just report the results] Every change flows through the same gates. Nothing reaches production without passing tests and quality checks, and no human has to remember the steps. Common mistakes and gotchas 1. Putting secrets in the workflow file Never type a password or API key directly into a workflow YAML, it's visible to anyone who can see the repo. Use GitHub Secrets and reference them with ${{ secrets.NAME }}. This is the single most important security rule here. 2. No tests, so CI checks nothing CI that "runs the tests" is only as good as the tests you have. A green check on a project with no real tests gives false confidence. CI and a solid test suite are a team, see the testing post. 3. Slow pipelines nobody waits for If your pipeline takes 40 minutes, people start merging without waiting for it, defeating the purpose. Cache dependencies, run independent jobs in parallel, and keep the feedback fast so people actually trust and use it. 4. Deploying from any branch Accidentally wiring deployment to run on every branch means half-finished work goes live. Gate deployment on the main branch (and ideally a manual approval for production), as in the needs/if examples above. 5. Ignoring a flaky pipeline If the pipeline fails randomly for unrelated reasons, people start ignoring red X's, and then miss a real failure. Fix flakiness promptly; a boy-who-cried-wolf pipeline is worse than none. Using AI and agents with GitHub Actions CI/CD is YAML-heavy and detail-sensitive, perfect territory for AI help. 1. Writing the workflow Describe your project, "a Python app that should run pytest on every pull request and deploy to production when merged to main", and an AI assistant generates the full workflow YAML with the right actions and structure. Minutes instead of copy-pasting from a dozen examples. 2. Decoding failures Pipeline failures produce long, cryptic logs. Paste the failing log into an assistant and ask "why did this fail?" It cuts through the noise: "your tests passed but the deploy failed because the API_TOKEN secret isn't set." 3. Reviewing for security and speed Ask AI to review a workflow for hard-coded secrets, overly broad permissions, or slow steps that could be cached or parallelized. It catches the expensive and risky mistakes before they bite. 4. Agents that open fix-it pull requests The frontier: connect an AI agent to your CI so that when a pipeline fails, the agent reads the logs, proposes a fix, and opens a pull request for a human to review. The tedious detective work is done; you stay in control of the merge. A word of caution: a CI/CD pipeline can deploy to production and holds access to secrets, it's a high-privilege system. Review AI-generated workflows carefully, never let generated config auto-deploy without a human approval gate, and double-check that no secret is exposed. Wrapping up GitHub Actions turns the repetitive, forgettable work of testing and shipping code into a reliable robot assembly line that runs the same way every time. You learned: What CI/CD is: automatically test every change (CI) and ship what passes (CD). The vocabulary: workflows, events/triggers, jobs, steps, actions, and runners. How to build one: a YAML file that checks out code, installs, tests, and (gated) deploys. The traps: secrets in files, missing tests, slow pipelines, deploying from any branch, and tolerating flakiness. The AI angle: generating workflows, decoding failures, security review, and auto-fix agents. Where to go next Add a five-line "run my tests" workflow to one repo and watch the green check appear on your next pull request. That first automated run is the hook. Move one secret out of your code and into GitHub Secrets, then reference it safely. Add a deploy job gated on needs: test. The moment broken code physically can't reach production, the Friday-deploy anxiety disappears. Let the robot run the assembly line, and nobody loses a weekend to a forgotten step again.