Use concrete secret names in README table and usage example

- cloudflare-pages-preview/README.md: secrets table now prescribes exact repo
  secret names (CF_PAGES_PREVIEW_API_TOKEN, CF_PAGES_PREVIEW_ACCOUNT_ID) with
  the literal passed-as YAML snippet. Usage example updated to match.
- CLAUDE.md: mandate the three-column table format with concrete names, and
  require usage examples to reference the same names
This commit is contained in:
Den Delimarsky 2026-03-10 16:47:40 +00:00
commit 2a230c7793
No known key found for this signature in database
2 changed files with 39 additions and 37 deletions

View file

@ -116,16 +116,23 @@ 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 covering every secret the caller
must configure. For each secret, document:
3. **Required secrets** — a dedicated section starting with a table with
**concrete** secret names and wiring. Prescribe exact names so callers can
copy-paste without deciding:
```markdown
| Repo secret name | Passed as | Value |
|---|---|---|
| `FOO_API_TOKEN` | `api-token: ${{ secrets.FOO_API_TOKEN }}` | ... |
```
Follow the table with a subsection per secret documenting:
- **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)
- **Minimum permission scope** — the least privilege that makes the
action work
The usage example must reference the same concrete secret names.
If no secrets are needed, state that explicitly.
4. **Caller requirements** — `permissions:`, fork-PR guards, concurrency

View file

@ -25,45 +25,40 @@ and cleaning them up when the PR closes.
## Required secrets
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`.
Create these secrets in the caller repo: GitHub → repo → **Settings → Secrets
and variables → Actions → New repository secret**.
| Repo secret name | Passed as | Value |
|---|---|---|
| `CF_PAGES_PREVIEW_API_TOKEN` | `api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}` | Cloudflare API token with `Account → Cloudflare Pages → Edit` permission, scoped to the single account that owns your Pages project |
| `CF_PAGES_PREVIEW_ACCOUNT_ID` | `account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}` | Cloudflare account ID (hex string from the dashboard sidebar) |
Both `deploy` and `cleanup` need the same two secrets.
### Cloudflare API token → `api-token` input
### `CF_PAGES_PREVIEW_API_TOKEN`
**Where to get it:** Cloudflare dashboard → **My Profile → API Tokens →
Create Token → Create Custom Token**.
**Permissions to configure:**
Cloudflare dashboard → **My Profile → API Tokens → Create Token → Create
Custom Token**. Configure:
| Type | Item | Permission |
|---|---|---|
| Account | Cloudflare Pages | Edit |
**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.
Under **Account Resources**, restrict to the single account that owns your
Pages project. Do **not** reuse an account-wide or general-purpose token — a
dedicated per-project token limits the blast radius of a leak.
Copy the token value into a repo secret, e.g. `CF_PREVIEW_API_TOKEN`.
### `CF_PAGES_PREVIEW_ACCOUNT_ID`
### Cloudflare account ID → `account-id` input
Cloudflare dashboard → select any domain, or the Workers & Pages overview →
the **Account ID** is in the right sidebar (copyable hex string).
**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 stored as one to keep it co-located with the token.
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 (no setup needed)
### 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.
The action defaults to `${{ github.token }}` (the automatic `GITHUB_TOKEN`),
which is sufficient for PR commenting with `pull-requests: write` permission.
## Caller workflow requirements
@ -110,8 +105,8 @@ jobs:
with:
directory: site/public
project-name: my-cf-pages-project
api-token: ${{ secrets.CF_PREVIEW_API_TOKEN }}
account-id: ${{ secrets.CF_PREVIEW_ACCOUNT_ID }}
api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}
account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}
cleanup:
if: >-
@ -122,8 +117,8 @@ jobs:
- uses: modelcontextprotocol/actions/cloudflare-pages-preview/cleanup@main
with:
project-name: my-cf-pages-project
api-token: ${{ secrets.CF_PREVIEW_API_TOKEN }}
account-id: ${{ secrets.CF_PREVIEW_ACCOUNT_ID }}
api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}
account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}
```
Note: `cleanup` does **not** require `actions/checkout` — it only calls the