Configure GitHub, publish, and deploy¶

This repository publishes the project's runtime documentation image. It uses a released builder image only to generate site/; it never publishes the shared Docs Toolkit builder.

This consumer¶

Configure GitHub Actions¶

In the consumer repository—not the toolkit repository—create a GitHub environment named production. GitHub environments are repository-scoped, so an environment with the same name elsewhere does not share its values.

Under Settings → Environments → production → Environment variables, add:

Under Settings → Environments → production → Environment secrets, add:

Copyable example for this consumer¶

Create these environment variables in the consumer repository's production environment. These values are public configuration, not secrets:

DOCS_TOOLKIT_IMAGE=harbor.norrsign.se/norrsign/docs-toolkit:v1
DOCS_IMAGE=harbor.norrsign.se/norrsign/docs-toolkit-consumer
SITE_NAME=Docs Toolkit Consumer
PROJECT_NAME=Docs Toolkit Consumer
PROJECT_DESCRIPTION=Consumer documentation generated by the Norrsign Docs Toolkit.
SITE_URL=https://docs-toolkit-consumer.norrsign.se
COPYRIGHT=© 2026 Norrsign
PROJECT_LOGO=assets/project/docs-toolkit-consumer-logo.svg
PROJECT_FAVICON=assets/project/docs-toolkit-consumer-favicon.svg

The public site is https://docs-toolkit-consumer.norrsign.se; the source repository is https://github.com/norrsign/docs-toolkit-consumer-project.

Create these environment secrets in the same environment. Replace the placeholders with the values created in Harbor; do not commit or print them:

HARBOR_USERNAME=robot$<Harbor-robot-account-name>
HARBOR_TOKEN=<Harbor-robot-account-token>

Create or update that Harbor robot account with these permissions:

The robot account needs pull access to norrsign/docs-toolkit and push access only to the repository in DOCS_IMAGE. Do not place those credentials in .env, GitHub variables, or Markdown.

What the workflow publishes¶

build-docs.yml runs when a vMAJOR.MINOR.PATCH Git tag is pushed, or when started manually from the Actions tab with a version input. It validates required variables, logs in to Harbor, builds the site, then builds and pushes the project's Nginx image:

${DOCS_IMAGE}:vMAJOR.MINOR.PATCH
${DOCS_IMAGE}:vMAJOR
${DOCS_IMAGE}:sha-<commit>

The exact semantic tag identifies one consumer release, such as :v1.0.0. The moving major tag, such as :v1, follows the newest compatible v1 consumer release. The SHA tag is immutable. This workflow does not publish :latest. The consumer version is independent of the builder version selected by DOCS_TOOLKIT_IMAGE.

Publish a consumer release¶

Validate and commit the intended consumer release, then create and push its semantic Git tag:

npm run check
git add docs
git commit -m "Update documentation"
git push origin main
git tag v1.0.0
git push origin v1.0.0

The tag must be in vMAJOR.MINOR.PATCH form and must point to the commit that should become the release. Pushing changes to main without a release tag does not publish an image.

For a manual release, select Actions → Build production documentation image → Run workflow, choose the commit or branch to release, and enter a version such as v1.0.0. Uncommitted local changes are not included. Wait for the workflow to complete, then confirm the semantic, major, and SHA tags in Harbor under the repository named by DOCS_IMAGE.

Deploy the published runtime image¶

On the host that serves the documentation, log in to Harbor and run the immutable tag from the successful workflow:

docker login harbor.norrsign.se
docker pull harbor.norrsign.se/norrsign/docs-toolkit-consumer:sha-<commit>
docker run --detach --name docs-toolkit-consumer --restart unless-stopped \
  --publish 8080:8080 \
  harbor.norrsign.se/norrsign/docs-toolkit-consumer:sha-<commit>

Put a TLS-terminating reverse proxy in front of port 8080 for public traffic. Use the exact semantic or immutable SHA tag for a pinned deployment. Use the moving major tag, such as :v1, only when the host is intentionally meant to follow compatible consumer releases.

Run on a Docker Compose host¶

.env.compose.example is the filled environment template for compose.production.yaml. It sets the production runtime image to harbor.norrsign.se/norrsign/docs-toolkit-consumer:v1, the container name, and the localhost port binding. It starts exactly one docs runtime service and contains no build or preview service, nor any Harbor credential.

On the production host, copy the template to the ignored environment file, authenticate to Harbor, and start it:

cp .env.compose.example .env.compose
docker login harbor.norrsign.se
docker compose --env-file .env.compose --file compose.production.yaml pull
docker compose --env-file .env.compose --file compose.production.yaml up --detach

Use docker compose --env-file .env.compose --file compose.production.yaml ps to confirm the service is running. Change DOCS_IMAGE_TAG to an exact version or SHA tag before starting it when the deployment must stay pinned. If no local reverse proxy is used, change DOCS_BIND_ADDRESS deliberately before exposing the port publicly.

Troubleshoot¶