From 05549c0320738b89754fe2d542751dfc304c8716 Mon Sep 17 00:00:00 2001 From: Den Delimarsky Date: Tue, 10 Mar 2026 16:45:57 +0000 Subject: [PATCH] Expand secrets docs: where to get values and how to set them - cloudflare-pages-preview/README.md: replace secrets table with per-secret subsections giving exact CF dashboard navigation for obtaining the API token (My Profile > API Tokens > Custom Token, Account > Pages > Edit permission) and account ID (right sidebar on any domain/Workers overview), plus explicit guidance to store each as a named repo secret - CLAUDE.md: README secrets section must now document the exact UI path to obtain each secret, minimum permission scope, input mapping, and storage location --- CLAUDE.md | 15 ++++++++-- cloudflare-pages-preview/README.md | 44 ++++++++++++++++++++++++------ 2 files changed, 47 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7968236..6960c75 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,9 +116,18 @@ Each action (or group) must have a `README.md` covering: 1. **What it does** — one paragraph per action 2. **Prerequisites** — external resources that must exist (CF project, etc.) -3. **Required secrets** — dedicated section listing every secret the caller - must configure: what it is, minimum permission scope, and which action - input it maps to. If no secrets are needed, state that explicitly. +3. **Required secrets** — dedicated section covering every secret the caller + must configure. For each secret, document: + - **Where to get it** — exact navigation path in the external dashboard/UI + (e.g. "Cloudflare → My Profile → API Tokens → Create Token") + - **Minimum permission scope** — the least privilege that makes the action + work + - **Which action input it maps to** — so callers know how to wire + `secrets.*` into `with:` + - **How to store it** — "repo secret named e.g. `FOO_TOKEN`" (suggest a + name; actual name is caller's choice) + + If no secrets are needed, state that explicitly. 4. **Caller requirements** — `permissions:`, fork-PR guards, concurrency 5. **Usage** — a minimal but complete caller workflow example 6. **Inputs/outputs** — tables with name, required, default, description diff --git a/cloudflare-pages-preview/README.md b/cloudflare-pages-preview/README.md index 7a40394..e826a7e 100644 --- a/cloudflare-pages-preview/README.md +++ b/cloudflare-pages-preview/README.md @@ -25,19 +25,45 @@ and cleaning them up when the PR closes. ## Required secrets -Configure these in the caller repo (**Settings → Secrets and variables → -Actions**) and pass them to the action via `with:`: +Create these secrets in the caller repo (GitHub → repo → **Settings → Secrets +and variables → Actions → New repository secret**), then pass them into the +action's `api-token` and `account-id` inputs. Secret names are your choice — +the example below uses `CF_PREVIEW_API_TOKEN` / `CF_PREVIEW_ACCOUNT_ID`. -| Secret | Passed as | What it is | +Both `deploy` and `cleanup` need the same two secrets. + +### Cloudflare API token → `api-token` input + +**Where to get it:** Cloudflare dashboard → **My Profile → API Tokens → +Create Token → Create Custom Token**. + +**Permissions to configure:** + +| Type | Item | Permission | |---|---|---| -| Cloudflare API token | `api-token` | Token with **`Pages:Edit`** permission scoped **only** to the target Pages project. Do not reuse a general-purpose or account-wide Cloudflare token — create a dedicated token per project. | -| Cloudflare account ID | `account-id` | Found in the Cloudflare dashboard sidebar. Not actually secret, but stored as one to co-locate with the token. | +| Account | Cloudflare Pages | Edit | -Both actions require the same two secrets. +**Account resources:** restrict to the single account that owns your Pages +project. Do **not** reuse an account-wide or general-purpose token — create a +dedicated one per project so a leak can't touch anything else. -The default `github-token` (`${{ github.token }}`) is sufficient for PR -commenting with the standard `pull-requests: write` permission — no additional -secret is needed there unless you want to comment as a different identity. +Copy the token value into a repo secret, e.g. `CF_PREVIEW_API_TOKEN`. + +### Cloudflare account ID → `account-id` input + +**Where to get it:** Cloudflare dashboard → select any domain or the Workers +& Pages overview → the **Account ID** is in the right sidebar (copyable hex +string, e.g. `a1b2c3d4...`). + +Not actually secret, but store it as a repo secret (e.g. +`CF_PREVIEW_ACCOUNT_ID`) to keep it co-located with the token. + +### GitHub token + +The action defaults to `${{ github.token }}` (the automatic +`GITHUB_TOKEN`), which is sufficient for PR commenting with +`pull-requests: write` permission. No additional secret is needed unless you +want comments posted under a different identity. ## Caller workflow requirements