GitHub Actions guides
Practical GitHub Actions guides: workflows, conditions, caching, deployments, security, debugging and runners, each one checked against GitHub's docs.
These guides are for teams that run a lot of CI and care about its speed and cost. Each one stands alone and was last checked in November 2026. Some end with how the same thing works on RunsOn, which runs your jobs on EC2 instances in your own AWS account.
New to GitHub Actions? Start with Your first workflow, then Triggers and Jobs, steps and needs.
Basics
Your first workflow What GitHub Actions is and how a workflow file works: on, jobs, runs-on and steps, with a first workflow you can copy, run, and extend. Triggers Every common GitHub Actions trigger: push and pull_request with branch, path and tag filters, activity types, schedule cron, and workflow_dispatch inputs. Jobs, steps and needs GitHub Actions jobs run in parallel on separate runners, steps in order on one. How needs chains jobs into stages, and when to use parallel steps instead.
Workflow logic
Conditions How if works on jobs and steps: the implicit success(), always() vs !cancelled(), failure(), running after a skipped job, and an expression cookbook. Concurrency Cancel superseded runs with cancel-in-progress, serialize deploys, and queue up to 100 pending runs with queue: max. Concurrency group keys and gotchas. Environment variables Every default GitHub Actions environment variable, how to set env at workflow, job and step level, GITHUB_ENV, GITHUB_PATH and vars. Passing data Pass a value or a file between steps and jobs: $GITHUB_OUTPUT, job outputs with needs, $GITHUB_ENV, artifacts, matrix outputs and size limits. Matrix strategy Run one job across OS, version and architecture combinations with strategy.matrix: include and exclude, fail-fast, max-parallel, dynamic JSON matrices. Parallel steps Run steps of one GitHub Actions job at the same time with parallel, background, wait and cancel, with a before/after setup that stops waiting in line.
Caching
Caching dependencies Cache npm, pip, Go, Gradle and other dependencies in GitHub Actions with actions/cache or setup-* built-in caching, and make restores faster. Cache keys and scopes Build a cache key with hashFiles, fall back with restore-keys, and learn cache immutability, branch scope, who can write the cache and the 10 GB limit. Docker layer caching Speed up Docker builds in GitHub Actions by caching layers with Buildx: the gha, registry, inline and local cache backends compared, with YAML examples.
Deployments, reuse and security
Environments GitHub environments: environment secrets and variables, required reviewers, branch rules and wait timers, deployment URLs, and deployment: false. OIDC with AWS Connect GitHub Actions to AWS with OIDC: the IAM identity provider, a role trust policy scoped by sub claim, configure-aws-credentials, and common errors. Triggering other workflows Start one GitHub Actions workflow from another: workflow_call, workflow_dispatch with gh, workflow_run, repository_dispatch, and the GITHUB_TOKEN rule. pull_request vs pull_request_target pull_request vs pull_request_target: which one gets secrets and a write token, the pwn request risk, 2025-2026 changes, and the safe split pattern.
Troubleshooting
Debugging Debug a failing workflow: ACTIONS_STEP_DEBUG and runner debug logs, why a job was skipped, gh run view, actionlint, act locally, and SSH into the runner. No space left on device Fix "No space left on device" in GitHub Actions: see what fills the disk, free space on ubuntu-latest, use /mnt, and get a runner with a bigger disk.
Runners
runs-on How runs-on picks a runner: GitHub-hosted labels, self-hosted label arrays, runner groups, and choosing the runner from a matrix or an expression. Larger runners GitHub larger runners from 2 to 96 vCPUs: Linux, Windows, arm64 and GPU sizes, per-minute prices, which plans get them, setup, and cheaper options. GPU runners Run GitHub Actions jobs on a GPU: GitHub's T4 runner and its limits, self-hosted GPU runners, and EC2 GPU runners with RunsOn, with prices and examples. Self-hosted runners Set up a self-hosted GitHub Actions runner step by step: register, run as a service, go ephemeral, keep it updated, and choose an autoscaler. Actions Runner Controller (ARC) Install Actions Runner Controller (ARC) with the gha-runner-scale-set-controller and gha-runner-scale-set Helm charts: GitHub App auth, labels and limits.