Release and Deployment Notes

There are two separate deployment stories in this repository:

1. The existing GitLab pipeline builds, tests, and publishes Debian .deb artifacts.
2. This Docusaurus site can be built and deployed manually to GitHub Pages.

They are intentionally independent. The documentation site does not modify .gitlab-ci.yml and does not participate in the Debian package release flow.

When you deploy the docs site, website/scripts/generate-debian-repo.mjs mirrors the latest GitHub Release .deb into a static Debian archive at https://download.edgewatch.com/debian/bastion/ (suite trixie, component main). End users can browse dists/trixie/ (Apache-style indexes) or configure:

deb [trusted=yes] https://download.edgewatch.com/debian/bastion trixie main

That mirror is unsigned; hosts use [trusted=yes] or verify SHA256 from the Downloads page first.

Debian package release flow

The GitLab pipeline has these stages:

Stage	Purpose
validate	ShellCheck scripts and Debian maintainer scripts, verify required files
build	Install build dependencies, fetch sources, compile, package
lint	Run lintian against the generated .deb
smoketest	Install the .deb in a clean Debian container and verify HTTP
publish	Publish to GitLab Package Registry and, on tags with credentials, GitHub Releases

Important CI variables include GITHUB_TOKEN for upstream GitHub API rate limits, PUBLIC_GH_TOKEN for public GitHub Release asset publication, OPENRESTY_VERSION to pin OpenResty, and PKG_REVISION to override the generated package revision.

Manual GitHub Pages deployment for these docs

Install dependencies once:

cd website
npm install

Build locally:

npm run build
npm run serve

Docusaurus' deploy command expects the deployment branch to exist in the target GitHub repository. For a new Pages repository, initialize gh-pages once before the first deploy:

ORGANIZATION_NAME=<github-user-or-org>
PROJECT_NAME=<github-pages-repo>
DEPLOYMENT_BRANCH=gh-pages
GIT_USER=<github-username>
REMOTE="https://${GIT_USER}@github.com/${ORGANIZATION_NAME}/${PROJECT_NAME}.git"
TMP_DIR="$(mktemp -d)"

git clone --depth 1 "${REMOTE}" "${TMP_DIR}"
cd "${TMP_DIR}"
git checkout --orphan "${DEPLOYMENT_BRANCH}"
git rm -rf . || true
printf '%s\n' "GitHub Pages branch for ${ORGANIZATION_NAME}/${PROJECT_NAME}." > README.md
touch .nojekyll
git add README.md .nojekyll
git commit -m "Initialize GitHub Pages"
git push origin "${DEPLOYMENT_BRANCH}"
cd -
rm -rf "${TMP_DIR}"

Deploy manually to GitHub Pages with Docusaurus' deploy command:

cd website
ORGANIZATION_NAME=<github-user-or-org> \
PROJECT_NAME=<github-pages-repo> \
DOCS_URL=https://<github-user-or-org>.github.io \
BASE_URL=/<github-pages-repo>/ \
GIT_USER=<github-username> \
npm run deploy

For SSH-based deployment, use REMOTE="git@github.com:${ORGANIZATION_NAME}/${PROJECT_NAME}.git" when initializing the branch, then deploy with SSH:

cd website
ORGANIZATION_NAME=<github-user-or-org> \
PROJECT_NAME=<github-pages-repo> \
DOCS_URL=https://<github-user-or-org>.github.io \
BASE_URL=/<github-pages-repo>/ \
USE_SSH=true \
npm run deploy

PROJECT_NAME is the GitHub repository Docusaurus pushes to. BASE_URL must match where browsers load assets. For the production custom domain download.edgewatch.com, use DOCS_URL=https://download.edgewatch.com and BASE_URL=/ (see npm run deploy:production in website/README.md). For default GitHub project pages at https://edgewatch.github.io/bastion/, use BASE_URL=/bastion/. Deploying with /bastion/ while serving on the custom domain root causes missing CSS.

Then configure the GitHub repository's Pages source to publish from the gh-pages branch. The generated website/static/.nojekyll file is copied into the static build output so GitHub Pages does not run Jekyll over Docusaurus assets.

Organization pages repository

If deploying to <github-user-or-org>.github.io, use a root base URL:

ORGANIZATION_NAME=<github-user-or-org> \
PROJECT_NAME=<github-user-or-org>.github.io \
DOCS_URL=https://<github-user-or-org>.github.io \
BASE_URL=/ \
npm run deploy

Manual static copy alternative

If you do not want Docusaurus to push for you, build the site and copy website/build/ into a checked-out GitHub Pages deployment repository or branch:

cd website
npm run build
rsync -a --delete build/ /path/to/github-pages-checkout/
cd /path/to/github-pages-checkout
git add .
git commit -m "Update documentation site"
git push

That approach is useful when the source repository remains GitLab-only and a separate GitHub repository owns Pages hosting.