Skip to content

Repository & CI Configuration

This page documents the complete configuration required to run the grantnorwood/beakin repository, including CI/CD pipelines, required secrets, and the Cloudflare Pages handbook publishing setup.

Repository overview

Item Value
Repository grantnorwood/beakin
Default branch main
Handbook source handbook/ (docs_dir in mkdocs.yml)
Handbook publish Cloudflare Pages → beakin-handbook project
Local preview tool scripts/handbook_serve.py

GitHub Actions workflows

handbook.yml — Deploy on merge to main

Trigger: push to main touching handbook/**, mkdocs.yml, or the workflow file itself.

What it does:

  1. Checks out the repo
  2. Verifies required Cloudflare secrets are present
  3. Installs pinned Python dependencies from requirements.txt
  4. Runs mkdocs build --strict --site-dir _site
  5. Deploys _site/ to Cloudflare Pages (beakin-handbook project, production)
  6. Publishes the production URL to the workflow summary

Runtime details: actions/setup-python@v6 with Python 3.12, actions/checkout@v6, timeout-minutes: 20

Required secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID (see below).

handbook-check.yml — PR preview

Trigger: pull request touching handbook/**, mkdocs.yml, requirements.txt, or the workflow file itself.

What it does:

  1. Checks out the repo
  2. Installs pinned Python dependencies from requirements.txt
  3. Runs mkdocs build --strict --site-dir _site
  4. Deploys _site/ to Cloudflare Pages as a PR-specific preview when repository secrets are available
  5. Writes the preview URL to the workflow summary and updates a single PR comment with the live preview link

Fork behavior: for pull requests from forks, the strict MkDocs build still runs, but the Cloudflare deploy step is skipped because repository secrets are not exposed to forked workflows.

Required secrets: same as above.

GitHub repository secrets

Secrets are stored at: Settings → Secrets and variables → Actions → New repository secret https://github.com/grantnorwood/beakin/settings/secrets/actions

Secret name Required by Description
CLOUDFLARE_API_TOKEN Both handbook workflows Cloudflare API token with Pages edit permissions (see setup below)
CLOUDFLARE_ACCOUNT_ID Both handbook workflows Your Cloudflare account ID (visible in the dashboard sidebar)
GITHUB_TOKEN Both handbook workflows Automatically provided by GitHub — no manual setup required

Cloudflare Pages setup (one-time)

1. Create the Pages project

Cloudflare Pages must know a project named beakin-handbook exists before the GitHub Action can deploy to it.

  1. Go to dash.cloudflare.com → Workers & Pages → Create application → Pages
  2. Choose "Upload your static files" (not "Connect to Git" — GitHub Actions owns the deploy)
  3. Name the project exactly: beakin-handbook
  4. Upload a dummy index.html to complete the wizard — the action will overwrite it on first deploy

2. Get your Account ID

In the Cloudflare dashboard, your Account ID appears in the right sidebar on any Workers & Pages page, or in the URL: dash.cloudflare.com/<account-id>/.

3. Create an API token

Use a Custom token — skip the pre-built templates, they grant more permissions than needed.

  1. Cloudflare dashboard → My Profile → API Tokens → Create Token → Custom token (bottom of the list)
  2. Set the following:
Field Value
Token name beakin-handbook-deploy (or anything)
Permissions Account → Cloudflare Pages → Edit
Account resources Include → your account
Zone resources (leave empty — not needed)
TTL (leave blank for no expiry)
  1. Click Continue to summary → Create Token
  2. Copy the token immediately — it is shown only once

4. Add secrets to GitHub

Go to https://github.com/grantnorwood/beakin/settings/secrets/actions and add:

  • CLOUDFLARE_API_TOKEN — the token from step 3
  • CLOUDFLARE_ACCOUNT_ID — the account ID from step 2

MkDocs configuration (mkdocs.yml)

Setting Value Notes
site_name Beakin Handbook
docs_dir handbook Source directory for handbook pages
theme.name material MkDocs Material theme
theme.palette slate (dark) first, default (light) Dark mode is the default
plugins search Built-in search index
Build flag --strict Both CI workflows fail on any warning
Output dir (CI) _site Added to .gitignore; never committed

Local development

Python dependencies

# from repo root
pip install -r requirements.txt

The repo pins Python 3.12.5 in .python-version so pyenv-managed shells and newly created virtual environments align with the GitHub Actions handbook workflows.

requirements.txt pins the MkDocs dependency set used by both CI and local preview. This installs into your active Python environment. The handbook_serve.py script uses its own isolated venv (.venv-handbook/), but it installs from the same requirements.txt file and re-installs automatically when that file changes.

Local preview server

python3 scripts/handbook_serve.py           # serves at http://127.0.0.1:8000
python3 scripts/handbook_serve.py --port 8001
python3 scripts/handbook_serve.py --no-open  # skip browser auto-open

Or use the VS Code task: 📖 Handbook: Serve (local preview).

The script auto-creates .venv-handbook/ and installs the pinned dependencies on first run. Subsequent runs skip the install step until requirements.txt changes.

.venv-handbook/   # isolated venv for mkdocs-material
_site/            # mkdocs build output

Adding a new handbook page

  1. Create handbook/<page-name>.md
  2. Add an entry to the nav: section in mkdocs.yml:
nav:
  - Home: README.md
  - User Guide: user-guide.md
  - Provisioning Guide: provisioning.md
  - Your New Page: page-name.md # ← add here
  1. Run python3 scripts/handbook_serve.py to verify it renders correctly before pushing.