Skip to main content

GitHub Actions

GitHub Actions is GitHub’s CI/CD automation tool. It can automatically run workflows for building, testing, deployment, and more. Public repositories are free to use, while private repositories come with a monthly free quota.

Basic Concepts

  • Workflow: an automated process made up of one or more jobs
  • Job(Task):a set of steps executed on the same runner
  • Step: a single task, which can be either an action or a shell command
  • Action(Action):reusable smallest unit
  • Runner: the server that executes the workflow

Basic Syntax

Workflow configuration files use YAML and live in the .github/workflows/ directory.

Simplest workflow

Complete example

Trigger events

Push Event

Pull Request Event

Scheduled tasks

Manual trigger

Common actions

Checkout code

Set up Node.js

Set up Python

CachingDependency

Upload build artifacts

Download build artifacts

Automatically publish a release

Create a release

automatically generates Release Notes

Self-hosted Runner

Self-hosted runners let you run workflows on your own servers.

Add a runner

  1. Go to Repository Settings → Actions → Runners → New self-hosted runner.
  2. Follow the prompts to install and configure it on your server.
  3. Start the runner.

Installation(Linux)

Use a self-hosted runner

Label selection

Secrets management

Add a secret

Settings → Secrets and variables → Actions → New repository secret

Use a secret

Matrix builds

Conditional execution

Practical examples

Automatically deploy to a server

Build and push Docker images

Code checks

Speed up CI without dropping checks

Coding agents write code faster than CI can verify it, so CI wait time becomes the bottleneck. The goal is to cut wait time without removing any check that protects a release. Work through these steps in order, and measure after each one. The list also works as a prompt for a coding agent: have it measure first, apply the steps, and report before-and-after numbers.

1. Measure where the time goes

Split each job into three parts: queued (waiting for a runner), setup (checkout, toolchains, dependencies), and work (build and tests). Slow CI is often slow setup, not slow tests.
started_at minus created_at is queue time. Each job’s steps array has its own timestamps, so you can split setup from work the same way.

2. Cancel superseded PR runs, but never main

github.head_ref is only set for pull request events, so new pushes to the same PR share a group and cancel the older run. Pushes to main fall back to the unique run_id, so every commit on main still gets a full run. A group such as ${{ github.ref }} would also cancel or replace queued main runs.

3. Skip docs-only changes without blocking merges

If a workflow is skipped by paths, paths-ignore, or branch filters, its required checks stay Pending and the PR cannot merge. A job skipped by an if: condition reports success. For required checks, let the workflow start and skip jobs instead:

4. Use the cache built into setup actions

  • actions/setup-node caches when you set cache: npm (or yarn, pnpm).
  • actions/setup-go caches by default.
  • For Rust, use Swatinem/rust-cache.
Cache storage is 10 GB per repository by default. Entries not used for 7 days are deleted, and when the repository is full, the least recently used entries are evicted, which can cause thrashing. Don’t cache what you won’t restore. Caches created by a pull_request run are scoped to that PR’s merge ref, so other PRs can’t reuse them. Run CI on push to main so PRs can restore a warm cache from the default branch.

5. Make a second build nearly free

Build twice locally. The second build should take almost no time. If it doesn’t, something is defeating the cache. Common causes are a Dockerfile that copies the whole repository before installing dependencies, or a build script that watches a file that doesn’t exist, so the target always looks stale.

6. Download tools instead of compiling them

go install and cargo install compile from source on every run. Download release binaries instead, or use an installer that fetches prebuilt binaries, such as cargo binstall or taiki-e/install-action for Rust tools.

7. Run independent jobs in parallel

Remove needs: entries that don’t pass outputs or artifacts. Split the longest test suite across several machines with a matrix.

8. Save macOS runners for work that needs macOS

On the Free, Pro, and Team plans, standard GitHub-hosted runners allow at most 5 concurrent macOS jobs, shared by all your workflows. Move formatting, lint, and dependency audits that don’t depend on the OS to ubuntu-latest.

9. Don’t do the same work twice

Don’t rerun a check that another job already ran. A frontend-only job doesn’t need to restore the Rust cache.

10. Compare before and after

Push the changes, rerun the measurement from step 1, and compare the same jobs. Look for the next slowest phase and repeat.

Best Practices

  1. Use caching to speed up dependency installation.
  2. Use matrix builds for multi-environment testing.
  3. Run jobs in parallel when they are independent.
  4. Use if wisely to save resources with conditional execution.
  5. Protect secrets and never print them in logs.
  6. Prefer official actions because they are more reliable and better maintained.
  7. Limit permissions and grant only what each workflow needs.
  8. Have a CI fallback plan — GitHub Actions outages happen regularly; consider self-hosted runners or a secondary CI platform.

Platform Reliability Risk

GitHub Actions has experienced frequent outages in 2025–2026. Mitchell Hashimoto (creator of Vagrant and Terraform, GitHub user #1299 since 2008) announced in April 2026 that his open-source project Ghostty is leaving GitHub, primarily because of persistent CI/CD reliability issues:
“I started marking each day with an X if GitHub outages affected my work. Nearly every day had an X.”
When your CI/CD platform has regular outages that block you for hours, it becomes a productivity risk — not just an inconvenience. For serious projects, consider:
  • Self-hosted runners as a fallback (see the Self-hosted Runner section above)
  • Alternative CI platforms (CircleCI, Buildkite, Gitea Actions)
  • Mirror your repo to another platform so you can switch CI quickly
  • Don’t couple your entire workflow to one platform’s availability

Mitigation Strategies

  1. Self-hosted runners — Run workflows on your own infrastructure; unaffected by GitHub outages
  2. Multi-platform CI — Mirror critical workflows to an alternative (CircleCI, Buildkite)
  3. Local testing first — Run lint/typecheck/test locally before pushing; CI should be a gate, not a bottleneck
  4. Cache aggressively — Reduce job duration so outages cause less blocked time
  5. Read-only GitHub mirror — Keep your source on GitHub for discoverability, but host CI elsewhere

References

Last modified on November 1, 2026