CI/CD with GitHub Actions: Complete Guide
Set up continuous integration and deployment with GitHub Actions: a starter test workflow, a gated deploy with environments, caching, secrets and permissions, with copy-ready YAML.

A teammate merged a pull request on a Friday afternoon. The tests had passed on his laptop, but the lockfile was out of date, and main no longer installed cleanly. Nobody noticed until the Monday deploy failed. A ten-line workflow would have caught it in two minutes. This post is the starter pipeline I set up for a new repository: tests on every push, a deploy that only runs after tests pass and a human approves it, and the handful of settings that keep it fast and safe.
If you already run a mature pipeline and want the deeper material, read Reliable CI/CD Pipeline Automation and the monorepo-specific CI/CD Pipeline Patterns for Monorepos. Here we start from zero.
Quick takeaways
- A workflow is a YAML file in
.github/workflows/with triggers, jobs and steps. Start with one that runs your tests. - Use
npm ci(or your language's lockfile install) in CI, never a plain install, so the build matches what you committed. - Make deployment a separate job that
needsthe test job and targets a protected environment. - Cache dependencies with the setup action's built-in cache option; it is one line.
- Give the workflow the least permission it needs, and pin third-party actions to a full commit SHA.
What does a basic GitHub Actions workflow look like?
This runs lint and tests for a Node project on every push to main and on every pull request, across two Node versions:
name: ci
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm run lint
- run: npm test
The triggers worth knowing are push, pull_request, schedule (cron syntax, useful for nightly jobs), and workflow_dispatch, which adds a manual "Run workflow" button. The concurrency block cancels an older run on the same branch when you push again, so you do not pay for results nobody will read. The matrix runs the same steps once per Node version, in parallel.
How do I deploy only after the tests pass?
Put deployment in its own job, make it depend on the test job, and attach it to a GitHub environment. In the repository settings you can require a reviewer for that environment, so a human clicks approve before production changes. Append this job under jobs: in the same file:
deploy:
needs: test
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
environment: production
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
- run: ./scripts/deploy.sh
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
Keep the deploy script in the repository so you can run it by hand when the pipeline itself is the problem. Whether it pushes to Vercel, a container registry or a server over SSH does not change the structure. Secrets stay out of the YAML: store them under the environment's settings and read them as secrets.NAME. They are not exposed to workflows triggered from forks, which is the behavior you want.
How do I make workflows faster?
Most slow pipelines are slow for one of three reasons. First, dependencies are downloaded every time: the cache: npm line above stores the package manager cache keyed by your lockfile (use cache: pip or cache: gradle for other ecosystems, or actions/cache for custom paths). Second, everything runs in sequence: split independent work, like lint and tests, into separate jobs so they run side by side. Third, Docker builds start cold; the BuildKit cache exports in docker/build-push-action fix that, as described in the reliable-pipelines post linked above. Measure from push to green before and after each change so you know what actually helped.
How do I keep the pipeline secure?
- Least privilege. Set
permissions: contents: readat the top and grant more per job only when needed. The default token is broader than most jobs require. - Pin actions. Tags move. Reference third-party actions by full commit SHA with a comment, for example
uses: owner/action@<40-char-sha> # v2.3.1, and let Dependabot propose updates. - Review what you import. An action runs with your repository's token. Prefer official or widely used actions, and read the source of small ones.
- Be careful with
pull_request_target. It runs with secrets in the context of the base branch; never check out and execute untrusted pull request code in it.
How can I reuse a workflow across repositories?
When three repositories run the same steps, copy-paste becomes maintenance debt. Move the shared job into a reusable workflow and call it:
# .github/workflows/node-ci.yml in a shared repo
on:
workflow_call:
inputs:
node-version:
type: string
default: "22"
# in each project
jobs:
ci:
uses: your-org/shared-workflows/.github/workflows/node-ci.yml@main
with:
node-version: "22"
Pin the @main to a tag or SHA once the shared workflow stabilizes, so a change there cannot break every project at once.
How do I know when something breaks?
Add the status badge to your README so the state of main is visible. For notifications, a final step with if: failure() can post to Slack or send an email. When a run fails and the log is not enough, re-run it with debug logging enabled from the Actions UI, and reproduce locally with npm ci && npm test in a clean checkout before touching the YAML.
What should I do next?
Create .github/workflows/ci.yml with the first example today and open a pull request to see it run. Once it is stable, enable branch protection on main so the test job is required, which is exactly the workflow described in Git Workflow Strategies for Teams. Add the gated deploy job only after a week of reliable test runs. If you containerize the app, the next step is the Docker and Kubernetes deployment guide.
Uğur Kaval
AI/ML Engineer & Full Stack Developer specializing in building innovative solutions with modern technologies. Passionate about automation, machine learning, and web development.


