Understanding CI/CD¶
CI (continuous integration) means: every push is checked automatically, by linters,
tests and a build. CD (continuous delivery or deployment) goes one step further and
rolls out what passed the checks, for example to tuxdex-srv. Instead of "I'll deploy
it later by hand", every change takes the same tested route.
git push ──► lint ──► test ──► build image ──► deploy to the server
│ │ │ │
└────────┴───────────┴── stops at the first error
The terms¶
| Term | GitHub Actions | GitLab CI | Meaning |
|---|---|---|---|
| Definition | .github/workflows/*.yml |
.gitlab-ci.yml |
The pipeline as a YAML file in the repository |
| Pipeline | Workflow run | Pipeline | One run, triggered by a push, a merge request or a schedule |
| Job | Job | Job | A group of steps on one runner; jobs can depend on each other |
| Step | Step | script line |
A single command or a ready-made action |
| Runner | GitHub-hosted or self-hosted runner | Shared or own gitlab-runner |
The machine that runs the jobs |
| Secret | Secret | CI/CD variable (masked, protected) | Passwords and keys, never in the YAML file |
| Artifact | Artifact | Artifact | Files a job hands on, such as a built package |
What you need to install¶
None of these tools is needed for the pipeline itself: it runs on GitHub or GitLab. They help you to watch and control pipelines from the terminal and to find mistakes before the push.
| Tool | For | Debian | Ubuntu | RHEL | Arch |
|---|---|---|---|---|---|
gh |
GitHub | sudo apt install gh |
sudo apt install gh |
repository cli.github.com, then sudo dnf install gh |
sudo pacman -S github-cli |
act |
GitHub, local runs | install script from nektos/act | install script from nektos/act | install script from nektos/act | sudo pacman -S act |
actionlint |
GitHub | release binary from GitHub | release binary from GitHub | release binary from GitHub | release binary from GitHub |
glab |
GitLab | sudo apt install glab |
sudo apt install glab |
.rpm from the glab releases |
sudo pacman -S glab |
gitlab-runner |
GitLab, own runner | repository packages.gitlab.com |
repository packages.gitlab.com |
repository packages.gitlab.com |
sudo pacman -S gitlab-runner |
yamllint |
all YAML | sudo apt install yamllint |
sudo apt install yamllint |
sudo dnf install yamllint (EPEL) |
sudo pacman -S yamllint |
pre-commit |
Git hooks | sudo apt install pre-commit |
sudo apt install pre-commit |
pipx install pre-commit |
sudo pacman -S pre-commit |
The gh package of Debian and Ubuntu is often a few versions behind. The repository at
cli.github.com has the current version for Debian and Ubuntu too.
A workflow for GitHub Actions¶
.github/workflows/ci.yml checks the shell scripts on every push and then builds the
Docker image from the Docker chapter:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check shell scripts
run: shellcheck scripts/*.sh
build:
needs: lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build image
run: docker build -t status-page:${{ github.sha }} .
needs: lint makes build wait for lint and skips it if lint fails.
Deploying to your own server¶
A deploy job logs in to the server over SSH with a key that is stored as a secret:
deploy:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Deploy to tuxdex-srv
env:
SSH_KEY: ${{ secrets.DEPLOY_KEY }}
KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
run: |
mkdir -p ~/.ssh
echo "$SSH_KEY" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519
echo "$KNOWN_HOSTS" > ~/.ssh/known_hosts
ssh deploy@status.example.com "cd /srv/status && docker compose pull && docker compose up -d"
On the server, the user deploy gets its own key with a restricted authorized_keys entry,
see ssh-keygen. The secrets are set with
gh secret.
The same for GitLab CI¶
.gitlab-ci.yml:
stages:
- lint
- build
lint:
stage: lint
image: debian:trixie
script:
- apt-get update && apt-get install -y shellcheck
- shellcheck scripts/*.sh
build:
stage: build
image: docker:29
services:
- docker:29-dind
script:
- docker build -t status-page:$CI_COMMIT_SHORT_SHA .
Each job runs in the given container image. Jobs of the same stage run in parallel, the stages one after the other.
Check locally first
actionlint, yamllint and pre-commit
find most mistakes in seconds, before a pipeline even starts. That saves a lot of
"fix CI" commits.
Secrets belong in the platform, not in the repository
A password in a workflow file is in the Git history forever and visible to everyone who can read the repository. Store it as a secret or CI/CD variable. GitHub and GitLab hide such values in the logs.