Skip to content
Event Route Optimiser Docs

GitHub Actions Docs Release Environment Setup

GitHub Actions Docs Release Environment Setup

1. Purpose

Define the exact GitHub Environments, secrets, and variables required by the docs release workflow for Core and ERO Starlight deployments to Cloudflare Pages.

This guide tells you what to copy from settings/.env* after environments are created.

2. Required GitHub Environments

Create these GitHub Environments in repository settings:

  1. docs-01-development
  2. docs-02-test
  3. docs-03-production

Recommended protection:

  • docs-03-production: live environment, require reviewers and wait timer if needed.
  • docs-02-test: next release environment, use reviewers when release validation needs approval.
  • docs-01-development: development environment, typically no required reviewers.

3. Required Environment Secrets

Set these secrets in docs-01-development, docs-02-test, and docs-03-production.

GitHub secret nameSource in settings filesNotes
CLOUDFLARE_API_TOKENCLOUDFLARE_API_TOKEN from settings/.env.localCloudflare API token used by Wrangler deploy action.
CLOUDFLARE_ACCOUNT_IDmirrored from SKNX_CLOUDFLARE_ACCOUNT_ID by sync script, fallback CLOUDFLARE_ACCOUNT_ID/TF_VAR_CLOUDFLARE_ACCOUNT_ID from env filesUse the Cloudflare account id for the target account.

4. Optional Environment Variables

Set these as GitHub Environment variables when you want release branding and project names to match your local settings.

GitHub variable nameSource in settings filesDefault if omitted
SKNX_ERO_AZURE_COMPANY_NAMESKNX_ERO_AZURE_COMPANY_NAME from settings/.env.localSynkronyx
SKNX_DOCS_PLATFORM_BRANDSKNX_DOCS_PLATFORM_BRAND from settings/.env.example or local envSynkronyXr
SKNX_DOCS_GITHUB_REPO_URLSKNX_DOCS_GITHUB_REPO_URL from settings/.env.example or local envhttps://github.com/synkronyx/event-route-optimiser
SKNX_DOCS_CORE_SITE_URLSKNX_DOCS_CORE_SITE_URL from settings/.env.example or local envhttps://docs.synkronyx.com in production, https://test-docs.synkronyx.com in test, and https://dev-docs.synkronyx.com in development
SKNX_DOCS_ERO_SITE_URLSKNX_DOCS_ERO_SITE_URL from settings/.env.example or local envhttps://ero-docs.synkronyx.com in production, https://test-ero-docs.synkronyx.com in test, and https://dev-ero-docs.synkronyx.com in development
SKNX_DOCS_CORE_TITLESKNX_DOCS_CORE_TITLE from settings/.env.example or local envSynkronyXr Core Docs
SKNX_DOCS_ERO_TITLESKNX_DOCS_ERO_TITLE from settings/.env.example or local envEvent Route Optimiser Docs
SKNX_DOCS_CORE_DESCRIPTIONSKNX_DOCS_CORE_DESCRIPTION from settings/.env.example or local envSynkronyx shared platform standards and governance
SKNX_DOCS_ERO_DESCRIPTIONSKNX_DOCS_ERO_DESCRIPTION from settings/.env.example or local envEvent Route Optimiser product documentation
CLOUDFLARE_CORE_PAGES_PROJECTif managed in settings, use your chosen canonical valuesknx-docs in production, sknx-test-docs in test, and sknx-dev-docs in development
CLOUDFLARE_ERO_PAGES_PROJECTif managed in settings, use your chosen canonical valuesknx-ero-docs in production, sknx-test-ero-docs in test, and sknx-dev-ero-docs in development
SKNX_CLOUDFLARE_ACCOUNT_IDcanonical source key in settings/.env* filesPreferred source key for Cloudflare account id in this repository.
TF_VAR_CLOUDFLARE_ACCOUNT_IDderived from SKNX_CLOUDFLARE_ACCOUNT_ID by sync scriptMirrored automatically for Terraform-style consumers that expect TF_VAR_* keys.

5. Release Routing Behavior

The workflow routes deployment environment automatically:

  1. release_environment=production uses docs-03-production (live).
  2. release_environment=test uses docs-02-test (next release).
  3. release_environment=development uses docs-01-development (development).

Tag rules:

  1. docs-release-v* deploys both Core and ERO.
  2. docs-core-v* deploys Core only.
  3. docs-ero-v* deploys ERO only.
  4. docs-test-release-v* deploys both Core and ERO to test.
  5. docs-test-core-v* deploys Core only to test.
  6. docs-test-ero-v* deploys ERO only to test.
  7. docs-dev-release-v* deploys both Core and ERO to development.
  8. docs-dev-core-v* deploys Core only to development.
  9. docs-dev-ero-v* deploys ERO only to development.

6. Verified Cloudflare Pages project to URL mapping

Recorded 2026-08-02 after DNS and Pages domain reconciliation.

Cloudflare Pages projectURLExpected HTTP status
sknx-docshttps://docs.synkronyx.com200
sknx-ero-docshttps://ero-docs.synkronyx.com200
sknx-dev-docshttps://dev-docs.synkronyx.com200
sknx-dev-ero-docshttps://dev-ero-docs.synkronyx.com200
sknx-test-docshttps://test-docs.synkronyx.com200
sknx-test-ero-docshttps://test-ero-docs.synkronyx.com200

7. Verification checklist

After secrets and variables are configured:

  1. Run workflow Docs Release to Cloudflare Pages manually for core and release_environment=development.
  2. Confirm deploy runs against docs-01-development.
  3. Run workflow manually for core and release_environment=test.
  4. Confirm deploy runs against docs-02-test.
  5. Run workflow manually for both and release_environment=production.
  6. Confirm production approval gate is enforced.
  7. Confirm Core and ERO Pages projects receive updated artifacts.

8. One-command synchronization from settings files

Use script scripts/sync-github-docs-environments.ps1 to create and update GitHub Environments, secrets, and variables from your settings/.env* files.

Examples:

Terminal window
# Dry run preview for all environments
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target all -WhatIf


# Apply updates for all environments
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target all


# Apply only production
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target production


# Apply only test
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target test


# Apply only development
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target development


# Apply only development using alias target
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target dev


# Legacy alias: both maps to all (production, test, development)
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target both


# Apply environment updates and repository-level variables
./scripts/sync-github-docs-environments.ps1 -Repository synkronyx/event-route-optimiser -Target all -SetRepositoryVariables

Required local prerequisites:

  1. GitHub CLI installed (gh).
  2. Valid gh authentication against github.com.
  3. Local settings/.env.local with CLOUDFLARE_API_TOKEN.
  4. Local environment files with Cloudflare account id where applicable:
    • settings/.env.dev.local
    • settings/.env.test.local
    • settings/.env.prod.local
  5. Optional defaults in settings/.env.example for docs branding values.

9. Security notes

  1. Never commit raw token values into any file under source control.
  2. Rotate CLOUDFLARE_API_TOKEN after initial setup if token was ever exposed outside secret storage.
  3. Keep production, test, and development secret values separate if different Cloudflare accounts are used.

10. GitVersion semantic versioning

Docs release versioning is GitVersion-driven and semantic:

  1. Workflow Docs Release to Cloudflare Pages runs GitVersion on every release build.
  2. GitVersion derives semVer from Git history and docs release tags.
  3. Build step exports SKNX_DOCS_RELEASE_VERSION to docs generation.
  4. Published Core and ERO sites display the release version in:
    • sidebar label
    • generated docs home page release callout

Commit message bump directives:

  • +semver: major
  • +semver: minor
  • +semver: patch
  • +semver: none

11. Pull request docs preview

Use workflow Docs PR Preview (.github/workflows/docs-pr-preview.yml) to deploy docs for PR review before merge.

Behavior:

  1. Triggered by pull request changes affecting docs content or docs build scripts.
  2. Builds Core and ERO docs with a PR semantic preview version (<semVer>-pr.<number>).
  3. Deploys both sites to Cloudflare Pages preview branch pr-<pull_request_number>.
  4. Posts preview URLs back to the PR as a bot comment.

Default preview projects:

  • Core previews use sknx-dev-docs.
  • ERO previews use sknx-dev-ero-docs.

Optional generic preview projects:

  • Set repository variable CLOUDFLARE_PR_CORE_PAGES_PROJECT (example: pr-docs).
  • Set repository variable CLOUDFLARE_PR_ERO_PAGES_PROJECT (example: pr-ero-docs).

When these are set, PR previews deploy to those project names instead of development project names.

Forked PR note:

  • Preview deploy is skipped for forked PRs because repository secrets are not exposed to forks.