⚙️ Introduction to GitHub Actions

What Are GitHub Actions?

GitHub Actions is an automation platform built directly into every GitHub repository. You describe when something should happen and what should happen, and GitHub runs it for you on its own servers — no separate CI service to configure.

💡 A useful analogy: Think of GitHub Actions like a smart-home system for your codebase. "When I arrive home (push code), turn on the lights (run the tests) and start the coffee (deploy the app)." You wire up the triggers once, and the automation runs itself from then on.

Because the automation lives in your repository as code, it's version-controlled alongside everything else — you can review changes to your CI/CD in a pull request, just like any other file.

The Five Building Blocks

Everything in GitHub Actions is made of five nested concepts. Learn these names and the YAML stops looking like a wall of text:

Anatomy of a Workflow File

Workflows are YAML files that live in .github/workflows/. GitHub automatically discovers and runs any workflow it finds there. Here is a minimal one, annotated:

name: CI Workflow            # Shown in the Actions tab

# WHEN: run on pushes and PRs targeting main
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# WHAT: the work to do
jobs:
  build:
    runs-on: ubuntu-latest   # The runner (VM) for this job
    steps:
      - uses: actions/checkout@v4      # Action: get your code onto the runner
      - name: Set up Node.js
        uses: actions/setup-node@v4    # Action: install Node
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci                    # Command: a shell step
      - name: Run tests
        run: npm test

Note the difference between the two kinds of steps: uses: pulls in a prebuilt action (someone else's reusable code, like actions/checkout), while run: executes a shell command directly on the runner.

A Real CI Workflow

The most common use of Actions is continuous integration: on every push and pull request, prove the code still builds and passes its tests. A matrix lets you run the same job across several versions at once — cheap insurance that your code works everywhere it needs to.

name: Node.js CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.x, 20.x, 22.x]   # Test on three Node versions
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'                       # Cache deps between runs
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

✓ test (18.x)   passed in 1m 04s
✓ test (20.x)   passed in 58s
✓ test (22.x)   passed in 1m 01s

Each matrix entry becomes its own parallel job with its own green check (or red X). If Node 22 breaks something that 20 didn't, you'll know immediately and exactly where.

Secrets & Environment Variables

Workflows often need sensitive values — an API token, a deploy key, a database URL. Never hard-code these into the YAML, which is committed to your repository for all to see. Instead, store them as encrypted secrets.

🔒 The analogy: A secret is a bank safe-deposit box. You lock the valuable away once; the workflow can reach in and use it when needed, but no one reading your code ever sees the contents.

Add one under Settings → Secrets and variables → Actions → New repository secret, then reference it with the secrets context:

steps:
  - name: Deploy to production
    run: ./deploy.sh
    env:
      API_TOKEN: ${{ secrets.API_TOKEN }}

GitHub automatically masks secret values in logs — even if a script accidentally prints one, it shows up as ***. GitHub also provides a built-in GITHUB_TOKEN secret automatically for authenticating with your own repository, so you rarely need to create a token for that.

Common Patterns

Scheduled jobs (cron)

The schedule event runs a workflow on a timer using cron syntax — perfect for nightly backups, dependency checks, or report generation:

name: Daily Database Backup

on:
  schedule:
    - cron: '0 2 * * *'      # Every day at 02:00 UTC

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Back up the database
        run: ./backup.sh
        env:
          DB_CONNECTION: ${{ secrets.DB_CONNECTION }}

Cache dependencies to run faster

Reinstalling packages from scratch on every run is slow. Caching restores them from a previous run, keyed on your lockfile so it invalidates automatically when dependencies change:

steps:
  - uses: actions/checkout@v4
  - name: Cache npm packages
    uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-node-
  - run: npm ci

Hands-on Exercise

Best Practices

Summary & Quiz

📚 Further Reading

• GitHub Actions Documentation
• GitHub Marketplace — Actions
• Using secrets in GitHub Actions
• Awesome Actions — a curated list

🚀 What's Next?

You've automated the software side. Next we shift from code to environments and ask a bigger question: how do we make an app run identically on every machine? That's the promise of containerization.