デプロイ手順書

octalab-docs を Cloudflare Pages にデプロイし、kb-gardener パイプラインを GitHub Actions で自動実行する構成の構築手順。

前提条件

GitHub リポジトリ（private）: slime-works/octalab-docs
Cloudflare アカウント
kb-gardener パッケージ（private）: slime-works/kb-gardener

アーキテクチャ

GitHub (slime-works/octalab-docs)
  │
  ├── push to main ──→ [deploy.yml] ──→ Cloudflare Pages
  │                      │
  │                      ├── uv sync (kb-gardener を private repo からインストール)
  │                      ├── mkdocs build
  │                      └── wrangler pages deploy (Functions 含む)
  │
  └── push to docs/inbox/** ──→ [gardener.yml]
                                  │
                                  ├── kb-gardener pipeline --stop-at verify
                                  └── kb-gardener publish (PR 作成)

リポジトリ構成

octalab-docs/
  .github/workflows/
    deploy.yml              # Cloudflare Pages デプロイ
    gardener.yml            # kb-gardener 自動パイプライン
  docs/                     # MkDocs ドキュメントソース
    inbox/                  # 未分類ドキュメントの投入先
    registry/
      concepts.yaml         # SKOS 概念レジストリ
      index.md              # 概念ツリー（concept-viz が生成）
  functions/                # Cloudflare Pages Functions
    registry/
      _middleware.js        # /registry/ への Basic 認証
  .env                      # ローカル用環境変数（git 管理外）
  .env.example              # テンプレート
  .gitignore
  kbg.yml                   # kb-gardener 設定
  mkdocs.yml                # MkDocs 設定
  pyproject.toml            # Python 依存定義
  wrangler.toml             # Cloudflare Pages 設定

Cloudflare Pages プロジェクト作成

Cloudflare Dashboard → Workers & Pages → 「作成」→ Pages

プロジェクト名: octalab-docs

初回デプロイ時に wrangler が自動作成するため、手動作成は不要。ただし初回のみ GitHub Actions で pages project create が必要（後述）。

GitHub Secrets の設定

GitHub リポジトリ → Settings → Secrets and variables → Actions → Repository secrets に以下を追加:

Secret 名	用途	取得方法
`KB_GARDENER_PAT`	private repo `slime-works/kb-gardener` へのアクセス	GitHub → Settings → Developer settings → Fine-grained personal access tokens → `slime-works/kb-gardener` に対して `Contents: Read-only` 権限で作成
`CLOUDFLARE_API_TOKEN`	Cloudflare Pages へのデプロイ	Cloudflare Dashboard → 任意のドメイン → API → API トークン → 「Cloudflare Pages の編集」テンプレートで作成
`CLOUDFLARE_ACCOUNT_ID`	Cloudflare アカウント識別子	Cloudflare Dashboard → 任意のドメイン → 概要 → 右サイドバー「API」セクションに表示
`ANTHROPIC_API_KEY`	kb-gardener の LLM 呼び出し（gardener.yml 用）	Anthropic Console で取得

wrangler.toml

Cloudflare Pages の設定ファイル。pages_build_output_dir を指定することで、wrangler がプロジェクトルートの functions/ ディレクトリを自動検出する。

name = "octalab-docs"
pages_build_output_dir = "site"
compatibility_date = "2025-01-01"

重要: wrangler.toml が存在すると、Cloudflare Dashboard の環境変数管理は「シークレット（暗号化変数）のみ」に制限される。通常の環境変数は wrangler.toml の [vars] セクションで管理する。

GitHub Actions ワークフロー

deploy.yml — Cloudflare Pages デプロイ

main ブランチへの push で自動実行。

name: Deploy to Cloudflare Pages
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: astral-sh/setup-uv@v4
      - run: |
          git config --global url."https://x-access-token:${{ secrets.KB_GARDENER_PAT }}@github.com/slime-works/".insteadOf "https://github.com/slime-works/"
      - run: uv sync
      - run: uv run mkdocs build
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy

ポイント:

git config --global url.*.insteadOf で private repo (slime-works/kb-gardener) への HTTPS アクセスに PAT を注入
wrangler pages deploy は引数なしで実行。wrangler.toml の pages_build_output_dir と name を参照する
wrangler がプロジェクトルートの functions/ を自動検出し、コンパイル・アップロードする

gardener.yml — kb-gardener 自動パイプライン

docs/inbox/ にファイルが push されたとき、または手動実行（workflow_dispatch）で起動。

name: KB Gardener Pipeline
on:
  push:
    paths: ["docs/inbox/**"]
  workflow_dispatch:

jobs:
  gardener:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: astral-sh/setup-uv@v4
      - run: |
          git config --global url."https://x-access-token:${{ secrets.KB_GARDENER_PAT }}@github.com/slime-works/".insteadOf "https://github.com/slime-works/"
      - run: uv sync
      - run: uv run kb-gardener pipeline --stop-at verify
      - run: uv run kb-gardener publish

ポイント:

permissions で contents: write と pull-requests: write を付与（publish ステップが branch 作成 + PR 作成するため）
pipeline --stop-at verify で inventory → lint → plan → apply → verify まで実行し、publish で PR を作成

Basic 認証（Pages Functions）

特定パスに HTTP Basic 認証を設置する。functions/ ディレクトリのファイルパス構造がルーティングに対応する。

ファイル配置

functions/
  registry/
    _middleware.js    # /registry/* に対して認証を要求

/registry/ 以外のパスには認証がかからない。別のパスにも認証を追加する場合は functions/<path>/_middleware.js を作成する。サイト全体に認証をかける場合は functions/_middleware.js をルートに配置する。

ミドルウェア実装

export async function onRequest(context) {
  const password = context.env.BASIC_AUTH_PASSWORD;

  // パスワード未設定時は認証をスキップ
  if (!password) {
    return context.next();
  }

  const username = context.env.BASIC_AUTH_USERNAME || "admin";
  const authorization = context.request.headers.get("Authorization");

  if (authorization) {
    const [scheme, encoded] = authorization.split(" ");
    if (scheme === "Basic") {
      const decoded = atob(encoded);
      const [user, pass] = decoded.split(":");
      if (user === username && pass === password) {
        return context.next();
      }
    }
  }

  return new Response("Authentication required", {
    status: 401,
    headers: {
      "WWW-Authenticate": 'Basic realm="Registry"',
    },
  });
}

Cloudflare 環境変数の設定

Cloudflare Dashboard → Workers & Pages → octalab-docs → Settings → Variables and Secrets

wrangler.toml が存在するため、シークレット（暗号化）としてのみ ダッシュボードから追加できる。

変数名	値	種類
`BASIC_AUTH_USERNAME`	任意のユーザー名	シークレット（Encrypt）
`BASIC_AUTH_PASSWORD`	任意のパスワード	シークレット（Encrypt）

注意: 環境変数を変更した後は再デプロイが必要。GitHub Actions から再実行するか、空コミットで push する:

git commit --allow-empty -m "trigger redeploy" && git push

pyproject.toml

kb-gardener を private GitHub リポジトリから直接インストールする。[build-system] セクションは不要（ドキュメントリポはパッケージではないため）。

[project]
name = "octalab-docs"
version = "0.1.0"
description = "Octalab Docs - MkDocs documentation site"
requires-python = ">=3.13"
dependencies = [
    "mkdocs>=1.6.1",
    "mkdocs-material>=9.7.1",
    "mkdocs-awesome-pages-plugin>=2.10.1",
    "mkdocs-git-revision-date-localized-plugin>=1.5.1",
    "pymdown-extensions>=10.0",
    "kb-gardener @ git+https://github.com/slime-works/kb-gardener.git",
]

ローカル開発

# 依存インストール
uv sync

# private repo へのアクセス（PAT が必要）
git config --global url."https://x-access-token:<PAT>@github.com/slime-works/".insteadOf "https://github.com/slime-works/"

# ドキュメントサイトをローカルで起動
uv run mkdocs serve --livereload

# kb-gardener パイプラインをローカルで実行
uv run kb-gardener pipeline --stop-at verify

# 概念レジストリの可視化を再生成
uv run kb-gardener concept-viz

.env に ANTHROPIC_API_KEY を設定しておくこと（.env.example を参照）。

初回デプロイ

初回は Cloudflare Pages プロジェクトが存在しないため、以下の手順で行う:

# 1. wrangler をインストール
npm install -g wrangler

# 2. Cloudflare にログイン
wrangler login

# 3. Pages プロジェクトを作成
wrangler pages project create octalab-docs --production-branch=main

# 4. 初回デプロイ
uv run mkdocs build
wrangler pages deploy

# 5. GitHub Secrets を設定（前述）
# 6. Cloudflare シークレットを設定（前述）
# 7. push して GitHub Actions で自動デプロイを確認
git push origin main

または、deploy.yml に初回のみ pages project create ステップを追加する:

- name: Create Pages project if needed
  uses: cloudflare/wrangler-action@v3
  continue-on-error: true
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    command: pages project create octalab-docs --production-branch=main

プロジェクト作成後はこのステップを削除してよい。

トラブルシューティング

症状	原因	対処
`wrangler pages deploy` で `Unknown arguments: functions-dir`	`--functions-dir` は `pages deploy` に存在しないフラグ	`wrangler.toml` の `pages_build_output_dir` を使い、引数なしで `pages deploy` を実行
`Project not found [code: 8000007]`	Cloudflare Pages プロジェクトが未作成	`wrangler pages project create <name> --production-branch=main` を実行
`Unable to authenticate [code: 10001]`	`accountId` が未指定	wrangler-action に `accountId` パラメータを追加
Basic 認証のダイアログが出ない	Functions がデプロイされていない	deploy ログで `Uploading Functions bundle` が出ているか確認。`wrangler.toml` の `pages_build_output_dir` が正しいか確認
正しい認証情報でログインできない	環境変数が設定されていない	`wrangler.toml` 使用時はダッシュボードの環境変数が「シークレット（暗号化）」でないと消える。シークレットとして再設定し、再デプロイ
`uv sync` で kb-gardener のインストール失敗	private repo へのアクセス権限がない	`git config --global url.*.insteadOf` で PAT を注入しているか確認。PAT に `Contents: Read-only` 権限があるか確認