From 53e82ef4177e6afcc677db13ddde7f0fda625804 Mon Sep 17 00:00:00 2001 From: Asgeir Jacobsen Date: Thu, 8 Oct 2026 10:50:01 +0200 Subject: [PATCH 1/2] Docs: add CI/CD documentation Explain how the GitHub Actions workflow checks every pull request and push to main, what each step does, and how the self-hosted runner on the VM is set up. AI usage: Claude Code was used for the structure and syntax of the markdown document and to make the writing clearer. --- docs/ci-cd.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/ci-cd.md diff --git a/docs/ci-cd.md b/docs/ci-cd.md new file mode 100644 index 0000000..d5cac8b --- /dev/null +++ b/docs/ci-cd.md @@ -0,0 +1,77 @@ +# CI/CD + +This page explains how our continuous integration (CI) works. + +## Summary + +- **CI is automated.** A GitHub Actions workflow checks every pull request and + every push to `main`. +- **CD is not automated yet.** Deploying to the VM is a manual step for now. We might add + automated CD later. + +## Continuous integration + +The workflow is defined in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml). + +### When it runs + +- On every pull request that targets `main`. +- On every push to `main` + +When a new commit is pushed to a branch that has an ongoing older run, the older run gets cancelled. (`concurrency` in the workflow). This saves runner time +and energy, and only the latest commit matters anyway. + +### What it does + +The workflow has one job, `checks`. It runs on our +[self-hosted runner](#the-self-hosted-runner) and performs these steps in order. The job stops at the first step that fails. + +| Step | What it checks | +| ---------------------- | ----------------------------------------------------- | +| `actions/checkout` | Fetches the code. | +| `actions/setup-node` | Installs Node.js 22 and caches npm downloads. | +| `npm ci` | Installs exactly the versions in `package-lock.json`. | +| `npm run lint` | ESLint for the frontend and the backend. | +| `npm run format:check` | Prettier formatting for the whole repository. | +| `npm test` | Vitest unit and component tests. | +| `npm run build` | Type-checks and builds the frontend and the backend. | + +### The self-hosted runner + +NTNU's GitHub Enterprise (`https://git.ntnu.no`) provides no hosted runners, so +the jobs run on a runner installed on our group's VM. + +**Setup.** A repository admin adds the runner under _Settings > Actions > +Runners > New self-hosted runner_ and runs the commands GitHub shows on the VM. +The registration token is single-use and must never be committed. The runner +lives in `~/actions-runner` and runs as a systemd service, so it survives +reboots (`sudo ./svc.sh install` and `sudo ./svc.sh start`). + +**If a CI run never starts**, the runner is probably down, because jobs stay +queued instead of failing. Check that the VM is on, then run +`sudo ./svc.sh status` in `~/actions-runner`. + +**Good to know.** Node.js is not preinstalled on the runner, which is why the +workflow uses `actions/setup-node`. Old builds pile up in +`~/actions-runner/_work`, so clear it if the disk fills up. + +### What it does not do yet + +- There are no end-to-end tests or API tests, because we have not chosen the + tools yet. The backend has no `test` script, so `npm test` skips it. +- It does not run against a database. The Python import script in + `backend/data` is not tested by CI. + +## Merging + +CI is one of two gates before a pull request can be merged into `main`. The +other is review. A pull request cannot be merged while CI is failing. + +If CI fails, open the failed run from the pull request page, read the log of +the failed step, and fix it on your branch. Pushing a new commit starts a new +run, and also dismisses existing approvals. + +## Continuous delivery + +Nothing is deployed automatically. After a merge to `main`, someone has to +update the VM by hand for now. \ No newline at end of file From 058f28cd90e21ea0598829446987e5507829653a Mon Sep 17 00:00:00 2001 From: Asgeir Jacobsen Date: Thu, 8 Oct 2026 11:05:49 +0200 Subject: [PATCH 2/2] Style: add missing newline at end of ci-cd.md --- docs/ci-cd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ci-cd.md b/docs/ci-cd.md index d5cac8b..5d42c58 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -74,4 +74,4 @@ run, and also dismisses existing approvals. ## Continuous delivery Nothing is deployed automatically. After a merge to `main`, someone has to -update the VM by hand for now. \ No newline at end of file +update the VM by hand for now.