GitHub Actions Fundamentals — Workflows, Jobs, Triggers, and Artefacts

Continuous Integration and Continuous Deployment (CI/CD) transforms software delivery from a manual, error-prone process into an automated, reliable pipeline. Every code push triggers automated tests, security scans, image builds, and deployments — catching bugs before they reach production, enforcing quality standards, and enabling multiple deployments per day with confidence. GitHub Actions is the native CI/CD platform for GitHub repositories, providing free compute for public repos and generous allowances for private ones, with a YAML-based workflow syntax that lives alongside your code.

GitHub Actions Core Concepts #

Complete CI Workflow — Pull Request Quality Gate #

# .github/workflows/ci.yml
# Runs on every push and pull request — the quality gate before merging

name: CI

on:
    push:
        branches: [main, develop, 'feature/**']
    pull_request:
        branches: [main, develop]

# Cancel in-progress runs for the same branch/PR (saves CI minutes)
concurrency:
    group: ci-${{ github.ref }}
    cancel-in-progress: true

env:
    NODE_VERSION:  '20'
    REGISTRY:      ghcr.io
    IMAGE_NAME:    ${{ github.repository }}

jobs:

    # ── Job 1: Lint and type check ────────────────────────────────────────
    lint:
        name:    Lint & Type Check
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: ${{ env.NODE_VERSION }}
                  cache: npm
                  cache-dependency-path: api/package-lock.json

            - name: Install API dependencies
              run: npm ci
              working-directory: api

            - name: Lint API
              run: npm run lint
              working-directory: api

            - name: Type check API
              run: npm run typecheck
              working-directory: api

            - name: Setup Node.js for Angular
              uses: actions/setup-node@v4
              with:
                  node-version: ${{ env.NODE_VERSION }}
                  cache: npm
                  cache-dependency-path: client/package-lock.json

            - name: Install Angular dependencies
              run: npm ci
              working-directory: client

            - name: Lint Angular
              run: npm run lint
              working-directory: client

    # ── Job 2: Test API ───────────────────────────────────────────────────
    test-api:
        name:    Test API
        runs-on: ubuntu-latest
        # Run lint first — skip tests if linting fails
        needs:   lint
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: ${{ env.NODE_VERSION }}
                  cache: npm
                  cache-dependency-path: api/package-lock.json

            - name: Install dependencies
              run: npm ci
              working-directory: api

            - name: Run unit tests with coverage
              run: npm run test:coverage
              working-directory: api
              env:
                  JWT_SECRET:      test-secret-for-ci
                  REFRESH_SECRET:  test-refresh-secret
                  NODE_ENV:        test

            - name: Upload coverage report
              uses: actions/upload-artifact@v4
              with:
                  name: api-coverage
                  path: api/coverage/
                  retention-days: 7

            - name: Check coverage thresholds
              run: |
                  COVERAGE=$(cat api/coverage/coverage-summary.json | \
                      node -e "const d=require('/dev/stdin'); \
                      console.log(d.total.lines.pct)")
                  echo "Line coverage: ${COVERAGE}%"
                  if (( $(echo "$COVERAGE < 80" | bc -l) )); then
                      echo "Coverage ${COVERAGE}% is below 80% threshold"
                      exit 1
                  fi

    # ── Job 3: Test Angular ────────────────────────────────────────────────
    test-angular:
        name:    Test Angular
        runs-on: ubuntu-latest
        needs:   lint
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: ${{ env.NODE_VERSION }}
                  cache: npm
                  cache-dependency-path: client/package-lock.json

            - name: Install dependencies
              run: npm ci
              working-directory: client

            - name: Run Angular tests (headless)
              run: npm run test:ci
              working-directory: client
              # test:ci = ng test --watch=false --browsers=ChromeHeadless

    # ── Job 4: Security audit ─────────────────────────────────────────────
    security:
        name:    Security Audit
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: ${{ env.NODE_VERSION }}

            - name: Audit API dependencies
              run: npm audit --audit-level=high
              working-directory: api

            - name: Audit Angular dependencies
              run: npm audit --audit-level=high
              working-directory: client

    # ── Job 5: Build check (Angular production build) ────────────────────
    build-check:
        name:    Build Check
        runs-on: ubuntu-latest
        needs:   [test-api, test-angular]
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: ${{ env.NODE_VERSION }}
                  cache: npm
                  cache-dependency-path: client/package-lock.json

            - name: Install Angular dependencies
              run: npm ci
              working-directory: client

            - name: Production build
              run: npm run build -- --configuration production
              working-directory: client

            - name: Upload build artifacts
              uses: actions/upload-artifact@v4
              with:
                  name: angular-build
                  path: client/dist/
                  retention-days: 1

How It Works #

Step 1 — Triggers Define When Workflows Run #

The on: section defines which GitHub events start the workflow. push: branches: [main, develop] runs on direct pushes to those branches. pull_request: branches: [main] runs when a PR is opened or updated targeting main. workflow_dispatch adds a manual trigger button in the GitHub UI. schedule: - cron: '0 2 * * *' runs nightly at 2am — useful for security scans and dependency updates.

Step 2 — needs Creates a Dependency Graph Between Jobs #

Jobs run in parallel by default. needs: lint makes a job wait for lint to succeed before starting. needs: [test-api, test-angular] waits for both. This creates a DAG (directed acyclic graph) of jobs — lint first, then tests in parallel, then build only if both tests pass. If any dependency fails, downstream jobs are skipped (not just failed). This is more efficient than serial jobs and cheaper than running all checks in one mega-job.

Step 3 — concurrency Cancels Superseded Runs #

concurrency: group: ci-${{ github.ref }} groups all runs for the same branch under one concurrency key. When a new push to feature/auth starts a CI run while a previous one is still running, the previous run is cancelled. This prevents CI queues from backing up and avoids wasting compute minutes on runs whose results are already obsolete. The group key using github.ref ensures only runs for the same branch cancel each other.

Step 4 — actions/setup-node cache Speeds Up Dependency Installation #

The cache: npm option on actions/setup-node caches the npm cache directory between runs. On cache hit, npm ci can resolve packages from the cache rather than downloading from the registry — turning a 60-second install into a 10-second restore. The cache key is derived from the package-lock.json hash — so the cache is invalidated whenever dependencies change.

Step 5 — Artifacts Pass Data Between Jobs #

upload-artifact saves files from one job; download-artifact retrieves them in a later job. The build job uploads the Angular dist/ folder, which the deploy job downloads and pushes to the server — without rebuilding. Coverage reports are uploaded for the PR comment bot to display. Artifacts are stored for a defined retention period and are accessible in the GitHub Actions UI for download and inspection.

Common Mistakes #

Mistake 1 — Running all steps in one giant job #

❌ Wrong — everything sequential, no parallelism, slow feedback:

jobs:
    everything:
        steps:
            - run: npm run lint
            - run: npm test         # waits for lint even if unrelated
            - run: npm run build    # waits for both even if only checking build

✅ Correct — parallel jobs with dependency graph:

jobs:
    lint: ...
    test:   { needs: lint }        # parallel once lint passes
    build:  { needs: test }        # only after tests pass

Mistake 2 — Hardcoding secrets in workflow YAML #

❌ Wrong — secret visible in git history forever:

env:
    JWT_SECRET: my-super-secret-key   # IN THE REPO — visible to everyone!

✅ Correct — reference from GitHub Secrets:

env:
    JWT_SECRET: ${{ secrets.JWT_SECRET }}   # encrypted in GitHub, never in code

Mistake 3 — Not caching dependencies #

❌ Wrong — npm ci downloads all packages from network on every run:

- uses: actions/setup-node@v4
  with:
      node-version: '20'
      # Missing: cache: npm

✅ Correct — enable npm caching:

- uses: actions/setup-node@v4
  with:
      node-version: '20'
      cache: npm
      cache-dependency-path: api/package-lock.json

Quick Reference #