github-actions

name	github-actions
title	GitHub Actions
category	Infra & CI/CD
description	Use to automate CI/CD — run tests on push/PR, build artifacts, and deploy — with workflow YAML, secrets, matrices, and caching.
tags	["ci","cd","automation","workflows","testing","deploy"]
official_docs	https://docs.github.com/actions
sources	["https://docs.github.com/en/actions/writing-workflows/quickstart"]
last_verified	2026-08-10T00:00:00.000Z

GitHub Actions — Skillship

Automate build, test, and deploy right in your repo. Workflows are YAML files in .github/workflows/ triggered by events (push, PR, schedule, manual).

🧭 When to use this skill

• Use when: you want tests to run on every push/PR, or to deploy on merge to main.
• Use when: you need scheduled jobs, release automation, or matrix testing across versions/OSes.
• Don't use for: secrets you can't scope to the repo/org (use a real secret manager for those).

⚡ Quickstart

CI workflow — .github/workflows/ci.yml

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: 22
          cache: npm            # caches ~/.npm keyed on package-lock.json
      - run: npm ci
      - run: npm test
      - run: npm run build

Commit it and every push/PR runs the job. See results under the repo's Actions tab.

🧩 Common recipes

Recipe: Use secrets (never hardcode)

      - name: Deploy
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: npx vercel deploy --prod --token "$VERCEL_TOKEN"

Add the secret in Settings → Secrets and variables → Actions.

Recipe: Test matrix (multiple versions / OSes)

    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "${{ matrix.node }}" }
      - run: npm ci && npm test

Recipe: Deploy to cloud with OIDC (no long-lived keys)

    permissions:
      id-token: write            # required for OIDC
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          aws-region: us-east-1

Recipe: Cancel superseded runs

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Recipe: Manual trigger with inputs

on:
  workflow_dispatch:
    inputs:
      environment: { type: choice, options: [staging, production] }

🚀 Ship to production

• Actions pinned to a version tag (@v4) or, for untrusted actions, a full commit SHA.
• permissions: set to least privilege (default the token to contents: read).
• Secrets stored in GitHub Actions secrets — never echoed to logs or committed.
• Prefer OIDC federation over storing cloud keys as long-lived secrets.
• Deploy job gated on a passing test job (needs:) and/or a protected environment.
• concurrency set for deploy workflows to avoid overlapping releases.

🔐 Security & secrets

• ${{ secrets.* }} are masked in logs; still avoid printing them. Don't pass secrets to untrusted PR workflows.
• pull_request from forks runs with a read-only token and no secrets by default — keep it that way.
• Pin third-party actions to a commit SHA to prevent supply-chain tag hijacking.

🐛 Common errors & fixes

Symptom	Likely cause	Fix
Workflow doesn't run	File not in .github/workflows/ or bad on:	Correct path + trigger; must be .yml/.yaml
Resource not accessible by integration	Token lacks permission	Add the needed scope under permissions:
Secret is empty in a fork PR	Secrets not exposed to fork PRs	Use pull_request_target carefully or a deploy gate on merge
Cache never hits	Wrong cache key/lockfile	Use setup-* built-in cache: or key on the lockfile hash
Deploy runs on failed tests	No job dependency	Add needs: [test] to the deploy job

📚 Sources

• https://docs.github.com/en/actions/writing-workflows/quickstart