GitHub Actions guide

What GitHub Actions does in production

GitHub Actions is built-in automation for repositories on GitHub (and GitHub Enterprise). Teams define workflows as YAML; GitHub schedules jobs on runners, executes steps (shell commands or marketplace actions), and surfaces pass/fail on commits and pull requests. It replaces or complements external CI servers like Jenkins when code already lives on GitHub.

Core concepts

Workflow — one YAML file; can contain multiple jobs
Job — runs on one runner; jobs in parallel unless needs: chains them
Step — a shell command or a reusable action
Runner — VM or container that executes the job (hosted or self-hosted)
Event — what triggers the workflow (push, pull_request, etc.)

Minimal workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

How a run executes

Trigger — event matches on: filters (branch, path, label)
Queue — GitHub assigns a hosted runner or waits for self-hosted
Checkout — actions/checkout clones the repo (shallow by default)
Steps — each step runs; failure stops the job unless continue-on-error
Artifacts / caches — optional upload for later jobs or retention
Status — check appears on commit/PR; required checks gate merges

Hosted vs self-hosted runners

GitHub-hosted runners (ubuntu-latest, windows-latest, macos-latest) are managed by GitHub — no maintenance, minute quotas apply. Self-hosted runners run on your VMs or Kubernetes; useful for private networks, GPU, or large builds. Register with a token; keep the runner service updated and isolate untrusted fork PRs.

Secrets and permissions

Repository and organization secrets are injected as env vars — never log them. GITHUB_TOKEN is auto-provided per job; scope it with permissions: (read vs write). Use Vault or cloud OIDC for short-lived cloud credentials instead of long-lived keys in secrets when possible.

Environments and deployments

Environments (e.g. staging, production) add protection rules — required reviewers, wait timers, branch restrictions. Deployment jobs can target Kubernetes or push images to Harbor / container registries after tests pass.

Reusable workflows and composites

Reusable workflow — call another workflow with workflow_call
Composite action — bundle steps in action.yml in-repo
Matrix — run the same job across OS versions or Node/Python versions

Where to look in the UI

Actions tab — workflow runs, logs per job/step
Settings → Secrets and variables — repo secrets and variables
Settings → Actions → Runners — self-hosted runner status
Branch protection — require status checks before merge

Learning resources

GitHub Actions docs — docs.github.com/actions
Workflow syntax — Workflow syntax reference
Security hardening — Security guides
Actions marketplace — github.com/marketplace

Troubleshooting →