Publish the manual to git-pages from Forgejo Actions
Some checks failed
ci / backend-docker (push) Successful in 0s
ci / build-5 (push) Successful in 49s
ci / web-checks (push) Successful in 38s
ci / upload-agent-releases (push) Successful in 38s
ci / web-build (push) Successful in 45s
ci / go-checks (push) Successful in 16m58s
ci / publish-release-manifest (push) Successful in 39s
ci / build-1 (push) Successful in 2m7s
ci / frontend-docker (push) Successful in 0s
ci / upload-sboms (push) Successful in 30s
ci / docs (push) Has been cancelled
ci / build-3 (push) Successful in 7m30s
ci / host-agent-docker (push) Successful in 0s
ci / build-4 (push) Successful in 42s
ci / build-2 (push) Successful in 8m2s
ci / chart-k8s-agent (push) Successful in 0s
ci / build (push) Successful in 10m13s
ci / agent-binaries (push) Successful in 19m0s
ci / sbom (push) Successful in 2m19s
ci / k8s-agent-docker (push) Successful in 0s
ci / server-binary (push) Successful in 11m51s
ci / chart (push) Successful in 0s

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Jonas Leder 2026-11-18 15:26:05 +01:00
commit 1b084d3d67
5 changed files with 87 additions and 20 deletions

View file

@ -343,3 +343,74 @@ jobs:
# An existing secret instead of inline values.
helm template ci "$CHART_DIR" --set secrets.existingSecret=vop-secrets > /dev/null
secrets: inherit
docs:
# Starts the server against Redis with local storage, fills it with demo data, captures the
# screenshots in a real browser, builds the manual with them (any missing image fails the
# build, DOCS_STRICT) and publishes it to git-pages on the default branch only.
needs: [server-binary]
runs-on: default
timeout-minutes: 60
container:
image: mcr.microsoft.com/playwright:v1.64.1-noble
env:
# The address the manual is published under, so that its links and images resolve.
DOCS_URL: https://jonasled.jonasled.dev/vulnerability-operator/
DOCS_STRICT: '1'
VOP_URL: http://localhost:8080
VOP_ADMIN_EMAIL: admin@localhost
STORAGE_BACKEND: local
REDIS_ADDR: localhost:6379
steps:
- name: Install tools
run: |
apt-get update -qq
apt-get install -y -qq --no-install-recommends git curl ca-certificates redis-server nodejs
- uses: https://code.forgejo.org/actions/checkout@v7
- uses: https://code.forgejo.org/forgejo/download-artifact@v4
with:
name: server-binary
path: bin
- name: Build the manual
run: |
set -eu
chmod +x bin/vop-server
export VERSION="1.0.$((GITHUB_RUN_NUMBER + VERSION_OFFSET))"
npm install -g pnpm@12.14.0
(cd site && pnpm install --frozen-lockfile)
# A new administrator password for every run. The server reads it only when its database is new.
export VOP_ADMIN_PASSWORD="$(head -c 24 /dev/urandom | base64 | tr -dc 'A-Za-z0-9')"
redis-server --daemonize yes
export GRYPE_DB_DIR="${GITHUB_WORKSPACE}/data/grype"
mkdir -p "${GRYPE_DB_DIR}"
export INITIAL_ADMIN_PASSWORD="${VOP_ADMIN_PASSWORD}" HTTP_ADDR=:8080 DB_DRIVER=sqlite DB_NAME="${GITHUB_WORKSPACE}/data/docs.db" STORAGE_DIR="${GITHUB_WORKSPACE}/data/storage" LOG_LEVEL=INFO
nohup bin/vop-server > server.log 2>&1 &
for i in $(seq 1 60); do
curl -fsS http://localhost:8080/readyz > /dev/null 2>&1 && break
sleep 2
done
curl -fsS http://localhost:8080/readyz || { tail -n 50 server.log; exit 1; }
cd site
export VOP_STATE="${GITHUB_WORKSPACE}/data/state.json"
node screenshots/seed.mjs
node screenshots/capture.mjs
pnpm build
pkill -x vop-server || true
- uses: https://code.forgejo.org/forgejo/upload-artifact@v4
if: always()
with:
name: docs
path: |
site/build/
site/static/img/screenshots/
server.log
retention-days: 7
- name: Publish to git-pages
# Only the default branch is published; other branches build the manual without publishing it.
if: github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch
env:
GIT_PAGES_TOKEN: ${{ github.token }}
run: |
curl -fsSL -o git-pages-cli https://codeberg.org/git-pages/git-pages-cli/releases/download/v1.13.1/git-pages-cli.linux-amd64
chmod +x git-pages-cli
./git-pages-cli "$DOCS_URL" --upload-dir site/build

View file

@ -88,13 +88,12 @@ console is on http://localhost:9001.
## Documentation
The docs used to be published at vulnerability-operator-8c2480.jonasled.dev (GitLab Pages). Pages are not available on Forgejo yet, so build them locally.
The docs are published at https://jonasled.jonasled.dev/vulnerability-operator/ (git-pages), built by the `docs` job.
The user guide, the administrator guide and the reference are in `site/`, built
with Docusaurus. The screenshots in them are not kept in the repository: each
pipeline used to capture them again from a server that holds demo data and publish
the result to GitLab Pages. Forgejo has no Pages, so that job is gone and the manual
is not published (tracked in jonasled/k8s-flux issue 5). See `site/README.md`.
run of the `docs` job captures them again from a server that holds demo data and publishes
the result to git-pages (default branch only). See `site/README.md`.
```sh
make docs # build the site into site/build
@ -303,9 +302,7 @@ filesystem. Everything it writes goes to the `/data` volume.
| upload-agent-releases, publish-release-manifest | publish the agent binaries (default branch only) |
| sbom, upload-sboms | make CycloneDX SBOMs of the binaries and images, and upload them to `sboms/<version>/` in the bucket (default branch only) |
| chart, chart-k8s-agent | render the charts, package them and push them to the project's OCI registry |
The documentation build (screenshots and Docusaurus site) and its GitLab Pages
publishing are not ported: Forgejo has no Pages (jonasled/k8s-flux issue 5).
| docs | capture the screenshots, build the Docusaurus manual and publish it to git-pages (default branch only) |
No job deploys the backend chart: Flux pulls it from the registry.

View file

@ -1,9 +1,9 @@
# Documentation site
The user guide, the administrator guide and the reference of Vulnerability Operator.
The site is built with [Docusaurus](https://docusaurus.io) and built locally. It
used to be published to GitLab Pages by the pipeline; Forgejo has no Pages, so
it is currently not published (jonasled/k8s-flux issue 5).
The site is built with [Docusaurus](https://docusaurus.io) and built by the `docs` job of
the Forgejo workflow and published to git-pages at
https://jonasled.jonasled.dev/vulnerability-operator/ from the default branch.
```text
site/
@ -63,8 +63,7 @@ each inside its theme div (`screenshot-light` or `screenshot-dark`), as in
## CI
The old GitLab pipeline built the web interface and the server, started the server with
Redis, ran the seed and the capture, built the site with `DOCS_STRICT=1` and published it
to GitLab Pages. The Forgejo workflow does not run these steps (no Pages on Forgejo,
jonasled/k8s-flux issue 5), so a broken link or a missing image is only found by a local
`make docs-screenshots`.
The `docs` job of `.forgejo/workflows/ci.yml` takes the server binary of the `server-binary`
job, starts it with Redis, runs the seed and the capture, builds the site with
`DOCS_STRICT=1` and, on the default branch only, uploads `site/build` to git-pages
(`git-pages-cli` with the automatic token of the run). Other branches build without publishing.

View file

@ -7,7 +7,7 @@ description: How this manual is written, how its screenshots are made in CI, how
# About this manual
This manual is part of the source code. It lives in the `site/` folder of the repository,
is built with [Docusaurus](https://docusaurus.io), and is published to GitLab Pages by the
is built with [Docusaurus](https://docusaurus.io), and is published to git-pages by the
continuous integration of the project. Each page describes the software at the commit that
was built, so the manual cannot fall behind the interface.
@ -17,11 +17,11 @@ On every change to the default branch, and on every merge request that touches t
the interface or the manual, the pipeline:
1. builds the web interface and the server from the same commit;
2. starts the server with a real Redis and a real S3 store, and fills it with demo data: two
2. starts the server with a real Redis and local storage, and fills it with demo data: two
clusters, three agents, one viewer account, two CPE mappings, alert rules and a report;
3. drives a headless browser through the pages, and captures each screenshot the manual uses;
4. builds the manual with the screenshots, failing if any image is missing;
5. publishes the manual to GitLab Pages, on the default branch only.
5. publishes the manual to git-pages, on the default branch only.
Because the screenshots are captured again on every run, a change to the interface shows up
in the manual on the next pipeline without anyone editing an image.

View file

@ -1,11 +1,11 @@
// @ts-check
// The documentation site of the vulnerability operator. It is published to
// GitLab Pages by the pages job of .gitlab-ci.yml; see README.md in this folder.
// git-pages by the docs job of .forgejo/workflows/ci.yml; see README.md in this folder.
const { themes } = require('prism-react-renderer');
// DOCS_URL is the address the site is published under, for example
// https://group.pages.example.com/vulnerability-operator. Without it the site
// https://jonasled.jonasled.dev/vulnerability-operator. Without it the site
// is served from the root of localhost, which is what `pnpm start` needs.
const docsUrl = new URL(process.env.DOCS_URL || 'http://localhost:3000/');
// CI builds with DOCS_STRICT=1: a missing screenshot then fails the pipeline