Setting up a CI/CD pipeline with GitHub Actions

This article explains how to set up a CI/CD pipeline with GitHub Actions, intended for developers who want to automate their build, test, and deployment process.

Requirements

- A GitHub account with a repository containing your code - Git 2.40.0 or newer installed on your local machine - Access to the repository settings (at least `write` permissions) - A project with a supported programming language (Node.js 20.x, Python 3.11, Java 17, or similar) - Optional: a deployment target such as a VPS, cloud platform, or container registry

Steps

1. Create the workflow directory

GitHub Actions reads workflow files from the `.github/workflows` directory in the root of your repository. Create this directory:

mkdir -p .github/workflows

2. Create the workflow file

Create a new file named `ci.yml` in the `.github/workflows` directory. This file defines the entire pipeline in YAML format.

touch .github/workflows/ci.yml

3. Define the workflow trigger

Open `.github/workflows/ci.yml` in your editor. Start with the name of the workflow and the triggers. The `push` trigger starts the pipeline on every commit to `main`, the `pull_request` trigger on every pull request to `main`:

name: CI/CD Pipeline</p><p>on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

4. Configure the build job

Add a job that builds the project. This job runs on an Ubuntu runner with Node.js 20. The `actions/checkout@v4` action fetches the code, and `actions/setup-node@v4` installs the correct Node.js version:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build

5. Add a test job

Add a second job that runs tests. This job depends on the build job via `needs`, so tests only run if the build succeeds. Use `actions/upload-artifact@v4` to preserve build results:

test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-results/

6. Add a deployment job

Add a deployment job that only runs on pushes to `main`, not on pull requests. Use `if` to check this. This job uses secrets for credentials — store those in the repository settings under Settings → Secrets and variables → Actions:

deploy:
    needs: test
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - name: Deploy to production
        run: |
          rsync -avz --delete dist/ user@yourserver.com:/var/www/html/
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

7. Commit and push

Commit the workflow files and push them to GitHub. The pipeline starts automatically:

git add .github/workflows/ci.yml
git commit -m "Add CI/CD pipeline with GitHub Actions"
git push origin main

8. Check the workflow run

Go to your repository on GitHub. Click on the Actions tab in the top navigation bar. You will see the workflow that has just started. Click on it to follow the execution of each step. Error messages appear directly in the log output.

Verification

Check whether the pipeline runs correctly by viewing the status of the latest run:

gh run list --limit 5

This command shows the last five workflow runs with their status (`completed`, `success`, `failure`). You need the GitHub CLI (version 2.40.0 or newer), installed and authenticated with `gh auth login`.

Frequently asked problems

1. Workflow does not start

Check that the file `ci.yml` is exactly in `.github/workflows/`, not in a subdirectory. Also check that the YAML syntax is correct — an indentation error of one space will cause GitHub to ignore the file. Validate the syntax with `npx yaml-lint .github/workflows/ci.yml`.

2. `npm ci` fails with "package-lock.json not found"

`npm ci` requires a `package-lock.json` file. Generate this locally with `npm install` and commit the file, or replace `npm ci` with `npm install` in the workflow.

3. Deployment fails with "Permission denied (publickey)"

The SSH key that you placed in the secret `SSH_PRIVATE_KEY` must match a public key in the `authorized_keys` of the target user on the server. Test the connection manually from your local machine with `ssh -i /path/to/key user@yourserver.com` before running the pipeline again.

This setup gives you a working CI/CD pipeline with separate build, test, and deployment phases. You can extend the jobs with additional steps such as container builds, security scans, or notifications — but the basic structure remains the same. The question is not whether your pipeline fails, but when — and how quickly you can find the logs that tell you why.

← Back to knowledge base