GitHub Actions Tutorial: Your First CI Workflow

GitHub Actions runs automated workflows when things happen in your repository: a push, a pull request, a schedule or a manual click. The most common first use is CI: run tests on every change.

Anatomy of a workflow

• Workflow - a YAML file in .github/workflows/.
• Trigger (on) - which events start it.
• Jobs - run in parallel by default, each on a fresh runner (virtual machine).
• Steps - shell commands or reusable actions, run in order.

A complete CI workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage
      - run: npm run build

Commit the file, open a pull request, and the checks appear on the PR. Combine with branch protection to require them before merging.

Adding a service like PostgreSQL

test:
  runs-on: ubuntu-latest
  services:
    postgres:
      image: postgres:17
      env:
        POSTGRES_PASSWORD: postgres
      ports: ['5432:5432']
      options: >-
        --health-cmd "pg_isready -U postgres"
        --health-interval 5s --health-retries 10
  env:
    DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres

Tips

• Use the major version tag of official actions (@v4) or, for third-party actions, pin a full commit SHA.
• Check the Actions tab for logs; each step is collapsible and searchable.
• Add workflow_dispatch: under on to get a "Run workflow" button.