GitHub Actions

The words

• Workflow: one automated process, defined in a YAML file in .github/workflows/ (for example ci.yml).
• Event (trigger): what starts the workflow, such as push or pull_request.
• Job: a set of steps that runs on one runner. Jobs run in parallel unless one needs another.
• Step: one command (run) or one action (uses), run in order inside a job.
• Action: a reusable step published by someone, such as actions/checkout, which fetches your code.
• Runner: the machine that runs a job. GitHub-hosted runners such as ubuntu-latest are fresh VMs for every job; self-hosted runners are your own machines.

Triggers

on:
  push:
    branches: [main]              # only pushes to main
  pull_request:                   # every pull request
  workflow_dispatch:              # a "Run workflow" button in the Actions tab
  schedule:
    - cron: "30 21 * * *"         # every day at 21:30 UTC, which is 03:00 IST

A complete workflow for a Node.js app

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

permissions:
  contents: read                  # least privilege for GITHUB_TOKEN by default

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [22, 24]    # two jobs, one per Node.js version
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm              # caches the npm download folder
      - run: npm ci
      - run: npm run lint
      - run: npm test

  build:
    needs: test                   # waits for every test job to pass
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v7
        with:
          name: web-dist
          path: dist/

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production       # required reviewers must approve first
    permissions:
      contents: read
      id-token: write             # allows an OIDC token for the cloud login
    steps:
      - uses: actions/download-artifact@v8
        with:
          name: web-dist
          path: dist/
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy
          aws-region: ap-south-1
      - run: aws s3 sync dist/ s3://shop-web-prod --delete

uses versus run

run executes shell commands on the runner, exactly as you would type them. uses runs an action, a packaged step with inputs given under with. Actions save you from writing the same setup again, but they are code written by someone else, so choose them carefully.

Expressions, env and secrets

Text inside ${{ }} is an expression that GitHub fills in, such as ${{ github.sha }} (the commit) or ${{ matrix.node-version }}. Secrets are stored in the repository or organisation settings and read with ${{ secrets.NAME }}. GitHub masks them in logs, but a careless script can still leak them, for example by printing them in a changed form.

      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Matrix builds, caching and artefacts

A matrix runs the same job for every combination of values: os [ubuntu-latest, windows-latest] times node-version [22, 24] gives 4 jobs. exclude removes combinations you do not need, and include adds extra ones. A matrix can create at most 256 jobs per workflow run.

Caching keeps downloaded dependencies between runs, keyed on a hash of the lock file, so the next run skips the download. setup-node can do it for you with cache: npm, or you can use actions/cache directly. Artefacts are files a job saves for later jobs or for people to download, such as a build folder or test reports: upload-artifact saves them and download-artifact fetches them.

Security basics

• Least privilege: set permissions at the top (contents: read) and give a job more only when it needs it. GITHUB_TOKEN is the automatic token each run gets.
• OIDC instead of long-lived keys: with id-token: write, a job can prove who it is to AWS, Azure or Google Cloud and get short-lived credentials. No cloud keys are stored in secrets at all.
• Pin third-party actions to a full commit SHA, like uses: some-org/some-action@<40-character-sha>, with the version in a comment. A tag like v2 can be moved to malicious code; a SHA cannot.
• Environments with required reviewers: a job that targets the production environment waits until an approved person clicks Approve.
• Pull requests from forks do not receive your secrets. Be very careful with the pull_request_target event, which runs with more power.