Skip to content

GitHub Actions CI/CD Pipeline

Medium ~45 min

What you'll build

A GitHub Actions workflow that runs linting and tests on every push, builds a Docker image on main, and deploys to a staging environment on successful builds.

Goals

  • Write GitHub Actions workflow YAML
  • Use jobs, steps, and actions
  • Manage secrets and environment variables
  • Implement conditional deployment stages

Prerequisites

  • Git and GitHub basics
  • YAML syntax
  • Understanding of CI/CD concepts

Steps

  1. 1

    Create the CI workflow

    Create a workflow file that runs on every push. It should install dependencies, lint, and run tests.

    Code
    # .github/workflows/ci.yml
    name: CI
    
    on:
      push:
        branches: [main, develop]
      pull_request:
        branches: [main]
    
    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: 20
              cache: npm
          - run: npm ci
          - run: npm run lint
          - run: npm test -- --coverage

    Expected result

    On every push and PR, the workflow runs lint and tests on Ubuntu with Node 20.

  2. 2

    Add a build job

    Add a build job that depends on the test job. It builds the production bundle and uploads it as an artifact.

    Code
    # Add to .github/workflows/ci.yml
      build:
        needs: test
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: 20
              cache: npm
          - run: npm ci
          - run: npm run build
          - uses: actions/upload-artifact@v4
            with:
              name: dist
              path: dist/

    Expected result

    The build job runs only after tests pass, and uploads the dist/ artifact.

  3. 3

    Build and push a Docker image

    Add a docker job that builds an image and pushes it to GitHub Container Registry. Use GitHub's built-in GITHUB_TOKEN for authentication.

    Code
    # Add to .github/workflows/ci.yml
      docker:
        needs: test
        if: github.ref == 'refs/heads/main'
        runs-on: ubuntu-latest
        permissions:
          packages: write
        steps:
          - uses: actions/checkout@v4
          - uses: docker/login-action@v3
            with:
              registry: ghcr.io
              username: ${{ github.actor }}
              password: ${{ secrets.GITHUB_TOKEN }}
          - uses: docker/build-push-action@v5
            with:
              context: .
              push: true
              tags: ghcr.io/${{ github.repository }}:latest

    Expected result

    On pushes to main, a Docker image is built and pushed to GHCR.

  4. 4

    Add deployment to staging

    Add a deploy job that runs after the docker job. It deploys the latest image to a staging server using SSH.

    Code
    # Add to .github/workflows/ci.yml
      deploy-staging:
        needs: docker
        runs-on: ubuntu-latest
        environment: staging
        steps:
          - uses: actions/checkout@v4
          - name: Deploy via SSH
            uses: appleboy/ssh-action@v1
            with:
              host: ${{ secrets.STAGING_HOST }}
              username: ${{ secrets.DEPLOY_USER }}
              key: ${{ secrets.DEPLOY_KEY }}
              script: |
                docker pull ghcr.io/${{ github.repository }}:latest
                docker compose up -d
          - name: Notify deployment
            run: echo "Deployed to staging at $(date)"

    Expected result

    After the Docker image is pushed, the deploy job SSHs to staging and restarts the service.

  5. 5

    Add status badges and branch protection

    Add CI status badges to the README and configure branch protection rules to require the CI workflow to pass before merging.

    Code
    # Add to README.md:
    ![CI](https://github.com/USER/REPO/actions/workflows/ci.yml/badge.svg)
    
    # Branch protection (via GitHub UI or API):
    # Settings → Branches → Add rule for 'main':
    #   - Require status checks to pass: CI / test
    #   - Require branches to be up to date
    #   - Require pull request reviews before merging

    Expected result

    The README shows a live CI badge, and main is protected — merges require passing CI.

Try it yourself

What you learned

You built a complete CI/CD pipeline with GitHub Actions — automated testing, building, image pushing, and deployment. The pipeline is the backbone of modern development, ensuring every change is validated before it reaches production.

Related Resources

Related Glossary

Related Glossary

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to topic