Skip to main content

Published

CI/CD in a small company: what it is and how to start

CI/CD is an automated process that, after a code change, runs the tests, builds the application and deploys it to a server using steps stored in the repository. For a team of 1–5 it usually pays off as soon as the application has users and deployment is a repeated manual job. Below I cover when it is worth doing and show a minimal GitHub Actions and Docker pipeline, including how to go back to the previous version.

  • CI/CD
  • GitHub Actions
  • Docker
  • Docker Compose
  • deployment
  • rollback

What CI/CD is

The abbreviation joins two practices. CI, continuous integration, makes sure every change entering the shared code passes automated checks. CD means continuous delivery or continuous deployment, and the difference between those comes down to whether a production deployment needs someone’s decision.

The set of steps is called a pipeline. What matters most for a small company is that the pipeline is a file in the repository, so anyone can see what will run, and the log shows which step stopped a deployment.

  • Continuous integration: tests run on every change, not when someone remembers them.
  • Continuous delivery: every change that passes is ready to release, but a person starts the deployment.
  • Continuous deployment: a change that passes goes to production on its own. The example below works this way, and if you prefer to decide by hand, replace its push trigger with workflow_dispatch.

When CI/CD pays off for 1–5 people

A small team rarely has a scale problem. It does have one person who knows how to deploy the application, and that person is sometimes away. I started on a team of three developers where deploying meant git pull on the production server, and merge conflicts were sometimes resolved right there. I wrote about it in the note on boring deployments.

Having no tests is no reason to wait. A first pipeline can simply build an image and deploy it, and tests can come later. That alone records the deployment steps and gives you versions to return to.

The cost is mostly the one-off setup. According to the GitHub Actions billing page, the Free plan includes USD 12 of monthly usage for private repositories, and standard runners in public repositories are free. GitHub’s documentation also says that storing images in GitHub Container Registry is currently free. This is the state as of November 2026, so check the current terms before you decide.

  • Worth it when the application has users and you deploy at least a few times a month.
  • Worth it when only one person can deploy, or the order of commands lives in someone’s head.
  • Worth it when someone edits code directly on the server or runs git pull there.
  • Worth it when the same errors keep returning after deployments because of a skipped step, such as a migration or clearing a cache.
  • It can wait for a prototype with no users or a site that changes twice a year.

The minimal setup

For one application on one server you need a GitHub repository, a Dockerfile, an image registry and a Linux server with Docker Compose. Kubernetes is not needed here. The flow is simple: push to main, tests, build an image tagged with the commit SHA, push it to the registry and deploy over SSH.

A SHA tag instead of latest gives each release its own fixed name and tells you which commit it came from. Going back to the previous version relies on this.

  • The Dockerfile has two stages: test, which runs the tests in a RUN instruction, and production, which holds only what should run on the server.
  • A failed RUN stops docker build, so the pipeline halts before the image is pushed.
  • The compose.yaml, app.env and deploy.sh files live on the server in /opt/app. The server does not need a copy of the repository to run the application.

The GitHub Actions pipeline

Save this file as .github/workflows/deploy.yml and replace ghcr.io/company/app with your image name. GitHub Container Registry requires the name in lowercase.

name: deploy

on:
  push:
    branches: [main]

# Two deployments at once would overwrite each other's state on the server.
concurrency:
  group: production

env:
  IMAGE: ghcr.io/company/app

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v7
      - name: Tests
        run: docker build --target test .
      - name: Build image
        run: docker build --target production -t "$IMAGE:$GITHUB_SHA" .
      - name: Push to registry
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          echo "$TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
          docker push "$IMAGE:$GITHUB_SHA"

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy over SSH
        env:
          SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
          KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
          TARGET: ${{ secrets.DEPLOY_TARGET }}
        run: |
          mkdir -p ~/.ssh
          printf '%s\n' "$SSH_KEY" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          printf '%s\n' "$KNOWN_HOSTS" > ~/.ssh/known_hosts
          ssh "$TARGET" /opt/app/deploy.sh "$GITHUB_SHA"
  • DEPLOY_SSH_KEY is a separate private key used only for deployments, with no passphrase, whose public part is on the server.
  • DEPLOY_KNOWN_HOSTS is the ssh-keyscan output for the server. Check the key fingerprint before saving it, because this secret is what protects you from connecting to someone else’s host.
  • DEPLOY_TARGET is an address in the form deploy@server-address.
  • GITHUB_TOKEN is created automatically for each run and does not need to be entered anywhere.

The server: compose.yaml

The image tag is a variable here. Compose reads it from the .env file written by the deployment script, so a server restart brings back the last successful release.

services:
  app:
    image: ghcr.io/company/app:${APP_TAG:?}
    restart: unless-stopped
    env_file: app.env
    ports:
      - '127.0.0.1:8080:8080'
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:8080/health']
      interval: 5s
      timeout: 3s
      retries: 12
  • The port is bound to 127.0.0.1 and a reverse proxy with TLS takes the traffic from the internet. Without this, a port published by Docker bypasses UFW.
  • Application secrets stay in app.env on the server, outside the image and the repository.
  • The healthcheck needs wget in the image and a /health endpoint in the application. In images without wget, use curl or a command from the application itself.
  • For a private image, log the server in to ghcr.io with a token that has the read:packages permission.
  • A deploy user in the docker group effectively has root on the host, so treat its key like an administrator key.

The server: deploy.sh

The same script handles both a deployment and going back to the previous version. Save it as /opt/app/deploy.sh and make it executable with chmod +x.

#!/usr/bin/env bash
set -euo pipefail

tag="${1:?Pass the full commit SHA}"
[[ "$tag" =~ ^[0-9a-f]{40}$ ]] || { echo "Invalid tag: $tag" >&2; exit 1; }

cd /opt/app
export APP_TAG="$tag"

docker compose pull app
docker compose up -d --wait app

# Save the tag only after a successful start, so .env points at a working release.
echo "APP_TAG=$tag" > .env
echo "$(date -Is) $tag" >> deploys.log
  • --wait waits for the healthcheck and fails when the container is unhealthy, so the pipeline turns red.
  • The format check rejects anything but a full SHA, including latest.
  • up -d replaces the container with a new one, so the application has a short gap. For deployments outside peak hours this is usually enough.
  • Run migrations between pull and up, in Laravel for example docker compose run --rm app php artisan migrate --force. The old version then runs on the new schema for a moment, so the migration has to be compatible with it.

How to go back to the previous version

Each release is a separate image in the registry, so going back means deploying the previous tag. Nothing has to be built and no server state has to be reconstructed. The list of recent releases is in deploys.log, and the first column says when each one went live.

ssh deploy@server-address tail -n 5 /opt/app/deploys.log
ssh deploy@server-address /opt/app/deploy.sh <full SHA of the previous release>
  • A release that failed its healthcheck keeps running until you run this command. The script deliberately does not roll back on its own, to stay short, so a red pipeline needs a person to react.
  • After going back, git revert the faulty commit. Otherwise the next push to main builds a new version with the same bug in it.
  • Going back to an old image does not undo database changes. That is why migrations should preferably add things, and removing a column should wait for a separate, later release. For a bigger data change, also have a backup you have already practised restoring.
  • Rollback only works while the old image is still in the registry, so registry cleanup rules have to keep the last few releases.
  • Do not roll back while a pipeline is running, because the manual command bypasses the concurrency lock.

What I checked and what I did not

I checked deploy.sh and compose.yaml locally on Docker 29.6 and Compose 5.3, with a local registry instead of ghcr.io and three test releases. Two deployments went through, the latest tag was rejected, and a release with a broken healthcheck made the script fail without changing .env. Going back to both earlier tags then worked, and after a stop and start Compose brought up the last successful release. A failing test stage also stops docker build.

The workflow file passed actionlint, but I did not run it in a real repository and did not test the SSH connection or the ghcr.io login. So on the first run, watch the log of the deployment step and practise going back to the previous version right away, before you need it.

What to add later

This setup deliberately leaves out a few things that often appear in larger configurations. Add them when a specific problem shows up.

  • Docker layer caching, when builds take too long, because the runner starts from nothing every time.
  • A staging environment, when changes have to be shown to someone before a release.
  • Zero-downtime deployments, when even a short gap is a problem.
  • Automatic rollback after a failed healthcheck, when nobody can react quickly to a red pipeline.

See also: CI/CD and Docker deployment, Deployment should be boring, Docker published ports bypass UFW.

To talk about a similar setup or problem, use the contact page.