English
GitHub Actions
Step 1. Why a machine checks every change
Why. Chatex already has strict rules: warnings are errors, the code style is checked on build, every model change needs a migration, 142 tests guard the behaviour. But rules that run only when someone remembers to run them protect nothing. A teammate forgets the format check, another has an old migration on their laptop, a third pushes "a tiny fix" without running the tests. And "it builds on my machine" proves little: your machine has caches, local settings and files that are not in the repository.
Continuous integration (CI) solves both problems: on every push a fresh machine checks out exactly what was pushed, runs every check, and marks the commit green or red for everybody to see. Problems are found minutes after they were made, by the person who made them.
Chatex uses GitHub Actions, the CI service built into GitHub. Jenkins, GitLab CI or Azure Pipelines would do the same job, but they need either another server or another hosting service; Actions works where the repository already lives and needs nothing but a YAML file in it. GitHub-hosted runners are free for public repositories; private repositories get a monthly quota of free minutes, far more than this project needs.
The vocabulary of GitHub Actions
Table 22.1 shows the terms used in this topic and the next two.
Table 22.1. GitHub Actions terms
| Term | Meaning | In Chatex |
|---|---|---|
| workflow | an automated process, one YAML file in .github/workflows/ | ci.yml (this topic), deploy.yml (topic 24) |
| event (trigger) | what starts a workflow: a push, a pull request, a button, another workflow | pull_request, push to dev, workflow_call |
| job | a set of steps that runs on one machine; jobs of a workflow run in parallel unless one needs another | backend, frontend |
| step | one command (run:) or one reusable action (uses:) inside a job; steps run in order, and the first failing step fails the job | Restore, Check formatting, npm ci, … |
| runner | the machine that runs a job; a GitHub-hosted runner is a fresh virtual machine for every job, deleted afterwards | ubuntu-latest |
| action | a reusable step published in a repository, referenced as owner/name@version | actions/checkout@v7, actions/setup-dotnet@v6 |
| artifact | files a job uploads and keeps with the run, for people or later jobs | test results here, the release package in topic 24 |
Step 2. The workflow file
Why. A workflow is code: it lives in the repository, is reviewed in pull requests and changes together with the project. GitHub runs every YAML file in .github/workflows/ automatically; there is nothing to configure on the website.
Do. Create the folders .github/workflows in the repository root and the file ci.yml in it. It is the final version; the next two chapters go through its two jobs step by step.
yaml
# Build, lint and test the backend and the frontend.
# Runs on pull requests and pushes to dev; deploy.yml calls it before every production deploy.
name: CI
on:
pull_request:
push:
branches: [dev]
workflow_call:
permissions:
contents: read
concurrency:
# Called from deploy.yml, github.workflow is the caller's name, so the groups never collide.
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
DOTNET_NOLOGO: true
DOTNET_CLI_TELEMETRY_OPTOUT: true
jobs:
backend:
name: Backend
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
with:
global-json-file: global.json
- name: Cache NuGet packages
uses: actions/cache@v6
with:
path: ~/.nuget/packages
key: nuget-${{ runner.os }}-${{ hashFiles('Directory.Packages.props', '**/*.csproj') }}
restore-keys: nuget-${{ runner.os }}-
- name: Restore
run: |
dotnet restore Chatex.slnx
dotnet tool restore
- name: Check formatting
run: dotnet format Chatex.slnx --verify-no-changes --no-restore
- name: Build
run: dotnet build Chatex.slnx -c Release --no-restore
- name: Check for model changes without a migration
run: dotnet ef migrations has-pending-model-changes --project Source/Chatex.Data --configuration Release --no-build
# Testcontainers starts PostgreSQL in the runner's Docker.
- name: Test
run: dotnet test --solution Chatex.slnx -c Release --no-build
- name: Upload test results
if: failure()
uses: actions/upload-artifact@v7
with:
name: test-results
path: '**/TestResults/**'
if-no-files-found: ignore
frontend:
name: Frontend
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
run:
working-directory: Source/Chatex.Web
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
cache-dependency-path: Source/Chatex.Web/package-lock.json
- run: npm ci
# Only what ships to browsers; run a full npm audit by hand when updating dev tooling.
- run: npm audit --omit=dev --audit-level=high
- run: npm run format:check
- run: npm run lint
- run: npm test -- --watch=false
- run: npm run buildYAML in two minutes
A workflow is a YAML document: key: value pairs, nesting by indentation with spaces (never tabs), lists with - at the start of the line. run: | starts a block of several lines, each executed as a shell command, so Restore runs two commands. Text after # is a comment. A wrong indentation does not produce an error in your editor, but GitHub refuses the file and shows the line on the Actions page.
Step 3. Triggers, permissions and concurrency
Why. The top of the file decides when the workflow runs and what it may do. Both are worth a careful look: a workflow that runs too rarely misses problems, and a workflow with too many rights is a risk.
Do. Read the header of ci.yml:
yaml
name: CI
on:
pull_request:
push:
branches: [dev]
workflow_call:
permissions:
contents: read
concurrency:
# Called from deploy.yml, github.workflow is the caller's name, so the groups never collide.
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
DOTNET_NOLOGO: true
DOTNET_CLI_TELEMETRY_OPTOUT: truename: CIis the name shown on the Actions page and next to commits.on:lists three events.pull_requestchecks every pull request — the merge result of the branch with its target, so a conflict that breaks the build is caught before merging.pushwithbranches: [dev]checks every push to the working branch.workflow_calllets another workflow call this one as a building block:deploy.yml(topic 24) runs the whole CI before every deployment instead of repeating the steps. A push tomainis not in the list on purpose: changes reachmainthrough pull requests, which are already checked, anddeploy.ymlchecks again.permissions: contents: readlimits the automatic token that every run receives (GITHUB_TOKEN) to reading the repository. A check needs nothing more, so even a compromised build tool could not push code or change issues. This is the principle of least privilege again, as for the database user and the service user later in this module.concurrency:puts runs into groups; withcancel-in-progress: truea new run cancels the older run of the same group. The group name is built from two expressions in double curly braces: the workflow name and the branch (github.ref). Three quick pushes todevtherefore cost one complete run, not three. The comment explains a subtle point: whendeploy.ymlcalls this workflow, the expressiongithub.workflowis the name of the caller ("Deploy"), so a deployment never cancels, and is never cancelled by, an ordinary CI run.env:sets environment variables for every step: no .NET welcome banner and no telemetry from the build machine.
Below the header, jobs: defines backend and frontend. They do not depend on each other, so GitHub starts them at the same time on two separate runners; the run takes as long as the slower job, not as long as both. Each job declares runs-on: ubuntu-latest — the current Ubuntu image of GitHub, with Docker, Git and common tools preinstalled — and a timeout-minutes limit, so a hanging test is stopped after 20 minutes instead of the default six hours.
Expressions and secrets in workflow files
An expression in double curly braces is evaluated by GitHub before the step runs. It may contain anything from the event, including the title of a pull request written by a stranger. Never put such an expression directly into a run: command: pass it through env: as deploy.yml does in topic 24, so the shell sees it as data, not as code.
Check
powershell
git status --shortThe output contains ?? .github/. GitHub checks the file when you push it in Running CI; until then make sure that your editor shows no tab characters in it.