A dependable GitHub Actions CI workflow gives every pull request a repeatable check for formatting, tests, builds, and supported runtime versions. This guide provides a reusable checklist plus copy-ready JavaScript, TypeScript, and Python workflow templates that you can adapt as your repository, package manager, or toolchain changes.
Overview
Continuous integration (CI) runs automated checks whenever code is pushed or a pull request is opened. GitHub Actions defines those checks in YAML files stored under .github/workflows/. A useful workflow should be predictable, reasonably fast, easy to diagnose, and strict enough to prevent known quality problems from reaching the default branch.
Before writing YAML, decide what the workflow must prove. A small library may need dependency installation, linting, tests, and a build. A web application may also need type checking, production bundling, and an accessibility or end-to-end test job. A Python service may need formatting, static analysis, unit tests, and a package import check.
Keep CI responsibilities visible. Put fast checks early, use the same commands developers run locally, and avoid hiding important behavior in long shell commands. If a command is valuable enough to run in CI, it should usually be documented in the repository's package scripts, Makefile, or task configuration as well.
Workflow design at a glance
| Design | Best fit | Main trade-off |
|---|---|---|
| Single runtime | Applications with one supported runtime | Fast and simple, but it can miss compatibility problems |
| Runtime matrix | Libraries or applications supporting several runtime versions | Better coverage, with more jobs and execution time |
| Monorepo jobs | Repositories containing multiple packages or services | More targeted, but requires clear change and dependency boundaries |
| Reusable workflow | Teams standardizing CI across repositories | Centralizes maintenance, but adds an interface between caller and workflow |
Checklist by scenario
Every repository
- Create a workflow under
.github/workflows/with a descriptive filename such asci.yml. - Choose events deliberately. Most projects need pull request validation and pushes to the default branch; scheduled or manual runs are optional.
- Set the runtime explicitly rather than relying on a runner's default environment.
- Install dependencies with the repository's lockfile-aware command.
- Run formatting checks, linting, tests, and builds as separate steps when that makes failures easier to identify.
- Give the workflow only the repository permissions it needs. Read-only contents access is a sensible baseline for many build-only jobs.
- Make sure secrets are not printed by shell commands, test output, or diagnostic logging.
JavaScript and TypeScript projects
Use the package manager already declared by the project. For npm, a committed package-lock.json normally pairs with npm ci. Projects using another package manager should configure its version explicitly and use its frozen or lockfile-enforcing install mode where available.
The following template assumes npm scripts named lint, test, and build. Remove or rename steps to match the repository rather than adding placeholder commands that always pass.
name: JavaScript and TypeScript CI
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
quality:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Install dependencies
run: npm ci
- name: Check formatting and lint
run: npm run lint
- name: Run tests
run: npm test
- name: Build project
run: npm run build
The action references and runtime value in this example are configuration choices to review against your repository's support policy. If formatting is a separate script, add a step such as npm run format:check before linting. For TypeScript, include the compiler in the normal build or add an explicit npm run typecheck command.
Testing several Node.js versions
Use a matrix when compatibility matters. Keep the matrix limited to versions the project actually supports; testing arbitrary versions creates noise rather than useful coverage.
jobs:
test:
strategy:
fail-fast: false
matrix:
node-version: [18, 20, 22]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm test
Use a separate build job if the build only needs to run once. This prevents identical build work from being repeated for every matrix entry.
Python projects
Python CI should make the interpreter version, dependency installation method, and test command explicit. The example below assumes a requirements.txt file and a pytest-based test suite. Replace those assumptions for Poetry, uv, pip-tools, a project-specific package build, or another supported setup.
name: Python CI
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: pip
cache-dependency-path: requirements.txt
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
- name: Check formatting
run: python -m ruff format --check .
- name: Run linting
run: python -m ruff check .
- name: Run tests
run: python -m pytest
If the project does not use Ruff, substitute the formatter and linter already specified by the project. A CI command should fail when the check fails; avoid appending || true unless the non-blocking behavior is intentional and documented.
Monorepos and reusable workflows
For a monorepo, start with correctness before optimization. A single install-and-test job is often easier to maintain. Once runtime or dependency cost becomes material, split jobs by package or use path filters carefully. Verify that a shared package change triggers every dependent package that needs testing.
Reusable workflows are useful when several repositories share the same policy. Define inputs for runtime versions, package-manager commands, or optional build steps, then document the interface. Keep repository-specific checks in the caller when centralization would make failures difficult to understand.
What to double-check
- Lockfiles: Confirm the lockfile is committed and the install command refuses unexpected dependency changes.
- Cache behavior: Cache package downloads, not generated build output, unless the cache key includes every input that affects the output. A stale cache should never be required for correctness.
- Runtime support: Align the matrix with the versions documented by the project. Check the runtime, operating system, database, and browser versions if they affect behavior.
- Pull request protection: Require the relevant CI checks before merging through repository branch settings. The job names must remain stable or the protection rules may point to obsolete checks.
- Permissions: Review
permissionsat workflow and job level. Jobs that only test code generally do not need write access to repository contents. - Forked pull requests: Treat untrusted pull request code as untrusted. Do not expose sensitive credentials to jobs that execute it, and be cautious with workflows that can write to the repository.
- Tests that need services: If tests require PostgreSQL, Redis, a browser, or another service, declare the service or setup step explicitly and make readiness checks reliable.
- Failure output: Preserve useful logs, test reports, and build artifacts when they help diagnose failures. Do not upload secrets or sensitive application data.
CI is also a good place to automate adjacent quality checks. For example, an API-heavy project can validate JSON schemas, while a frontend project can run accessibility checks. Keep these checks close to the code they protect and name them clearly so a failed pull request points to an actionable problem.
Common mistakes
Using a command the repository does not define
A template that calls npm run check is not useful if no such script exists. Inspect package.json, pyproject.toml, Makefiles, and project documentation before copying a workflow. The same principle applies to Python dependency files and test discovery settings.
Testing only the default runtime
A green build on one runtime does not establish compatibility with every supported runtime. Add a matrix when the project promises multiple versions, and keep the matrix synchronized with the support documentation.
Installing floating dependencies
Installing without a lockfile can make an unchanged commit produce different results over time. Use reproducible installation in CI, and create a deliberate dependency-update process rather than allowing every run to resolve a new graph.
Combining everything into one step
A single command can be compact, but it makes it harder to see whether formatting, linting, tests, or the build failed. Separate important checks unless the repository has a strong reason to combine them.
Optimizing before measuring
Caching, path filters, parallel jobs, and conditional builds can reduce execution time, but each adds maintenance and failure modes. First establish a correct baseline. Then use job timing and repeated failures to choose the smallest optimization that solves the actual problem.
When to revisit
Review the workflow whenever its inputs change, not only when CI fails. Revisit it before a planned development or release cycle, after upgrading a runtime or package manager, when the lockfile format or dependency strategy changes, and when a repository adds a new package, service, test suite, or deployment target.
Also review action references and cache configuration when the workflow platform or major language tooling changes. Confirm that the selected runtime versions remain supported by the project, that action inputs still match the documented interface, and that branch protection still requires the checks that matter.
Use this short maintenance routine:
- Run the same formatter, linter, tests, and build locally using the documented commands.
- Open the workflow and list every assumption: runtime, package manager, lockfile, services, secrets, and operating system.
- Compare those assumptions with the current repository files and support policy.
- Make a small workflow change, open a test pull request, and inspect both successful and failed logs.
- Confirm required status checks and permissions after the change.
- Record any non-obvious setup in the repository documentation so the next contributor can reproduce it.
A CI workflow is most valuable when it remains understandable months after it was written. Start with explicit, copy-ready checks; add matrix coverage and reusable components only where they provide clear value; and return to this checklist whenever the codebase, runtime, or workflow tooling changes.