GitHub Actions guides
How to write GitHub Actions workflows that run fast and stay safe: triggers, conditions, caching, OIDC, debugging and runners, with YAML you can copy.
We build RunsOn, which runs GitHub Actions jobs on EC2 for a lot of teams, and the same questions keep coming up: why did this workflow run, why does the cache never hit, how do I deploy to AWS without a long-lived key. These guides are our answers, with workflow files you can paste into your repo. A few end with how it works on RunsOn; the rest applies to any runner.
- 23 guides
- 6 topics
- updated November 2026
New to GitHub Actions? Start with Your first workflow, then Triggers and Jobs, steps and needs.
Basics3 guides #
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 logic6 guides #
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.
Caching3 guides #
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 security4 guides #
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.
Troubleshooting2 guides #
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.
Runners5 guides #
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.