From a979932c2f249f48a9153add7719f2cd56c3cdc1 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 8 Mar 2026 15:49:50 +0000 Subject: [PATCH] docs: clarify PAT requirements for gist subscriber store Explain both classic PAT (gist scope) and fine-grained PAT (Gists read/write) options across all docs. Add direct links to both token creation pages. Previous docs were vague about which token types work. Co-Authored-By: Claude Opus 4.6 --- README.md | 4 ++-- site/src/content/docs/configuration/environment.mdx | 2 +- site/src/content/docs/getting-started.mdx | 2 +- site/src/content/docs/subscriber-stores/gist.mdx | 11 +++++++---- 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 7726457..f06e4d4 100644 --- a/README.md +++ b/README.md @@ -128,13 +128,13 @@ SUBSCRIBER_STORE=gist | Variable | Description | |---|---| | `GITHUB_GIST_ID` | ID of a private Gist containing `subscribers.json` | -| `GITHUB_TOKEN` | GitHub PAT with `gist` scope (the default Actions token cannot access private gists) | +| `GITHUB_TOKEN` | PAT with gist access: classic PAT with `gist` scope, or fine-grained PAT with Gists read/write (the default Actions token cannot access private gists) | **Setup:** 1. Create a [secret Gist](https://gist.github.com/) with a file named `subscribers.json` containing `[]` 2. Copy the Gist ID from the URL -3. Create a PAT with `gist` scope +3. Create a PAT with gist access — [classic PAT](https://github.com/settings/tokens/new) with `gist` scope, or [fine-grained PAT](https://github.com/settings/tokens?type=beta) with Gists read/write 4. Add both as repo secrets (`SUBSCRIBERS_GIST_ID`, `SUBSCRIBERS_GIST_TOKEN`) Same file format as the JSON store: diff --git a/site/src/content/docs/configuration/environment.mdx b/site/src/content/docs/configuration/environment.mdx index 23323e5..f91871f 100644 --- a/site/src/content/docs/configuration/environment.mdx +++ b/site/src/content/docs/configuration/environment.mdx @@ -63,7 +63,7 @@ See [LLM Providers](/llm-providers) for setup details. | Variable | Description | |---|---| | `GITHUB_GIST_ID` | ID of a private Gist containing `subscribers.json` | -| `GITHUB_TOKEN` | GitHub PAT with `gist` scope (the default Actions token cannot access private gists) | +| `GITHUB_TOKEN` | PAT with gist access: classic PAT with `gist` scope, or fine-grained PAT with Gists read/write (the default Actions token cannot access private gists) | ### Google Sheets diff --git a/site/src/content/docs/getting-started.mdx b/site/src/content/docs/getting-started.mdx index f6b98c6..7daebc1 100644 --- a/site/src/content/docs/getting-started.mdx +++ b/site/src/content/docs/getting-started.mdx @@ -91,7 +91,7 @@ If your repo is **public**, don't use the default JSON subscriber store — `sub ```bash SUBSCRIBER_STORE=gist GITHUB_GIST_ID=your_gist_id -GITHUB_TOKEN=ghp_your_pat # PAT with gist scope +GITHUB_TOKEN=ghp_your_pat # PAT with gist access (classic: gist scope; fine-grained: Gists read/write) ``` See [GitHub Gist Store](/subscriber-stores/gist) for setup steps. diff --git a/site/src/content/docs/subscriber-stores/gist.mdx b/site/src/content/docs/subscriber-stores/gist.mdx index 68f18db..dcb3875 100644 --- a/site/src/content/docs/subscriber-stores/gist.mdx +++ b/site/src/content/docs/subscriber-stores/gist.mdx @@ -21,9 +21,12 @@ Create a [new secret Gist](https://gist.github.com/) with a file named `subscrib Copy the Gist ID from the URL (e.g., `https://gist.github.com/yourname/abc123def456` → `abc123def456`). -### 2. Create a GitHub PAT with `gist` scope +### 2. Create a GitHub PAT with gist access -The default `GITHUB_TOKEN` in Actions is scoped to the repository and **cannot access private gists**. Create a [fine-grained PAT](https://github.com/settings/tokens?type=beta) or classic PAT with the `gist` scope. +The default `GITHUB_TOKEN` in Actions is scoped to the repository and **cannot access private gists**. Create one of: + +- **[Classic PAT](https://github.com/settings/tokens/new)** — check the `gist` scope +- **[Fine-grained PAT](https://github.com/settings/tokens?type=beta)** — enable **Gists** → Read and write under Account permissions ### 3. Add repository secrets @@ -45,7 +48,7 @@ export GITHUB_TOKEN=ghp_your_pat_here | Variable | Required | Description | |---|---|---| | `GITHUB_GIST_ID` | Yes | ID of the private Gist | -| `GITHUB_TOKEN` | Yes | GitHub PAT with `gist` scope (the default `GITHUB_TOKEN` in Actions cannot access private gists) | +| `GITHUB_TOKEN` | Yes | PAT with gist access — classic PAT with `gist` scope, or fine-grained PAT with Gists read/write (the default Actions token cannot access private gists) | ## File format @@ -95,7 +98,7 @@ Sent emails are logged to an `email-log.json` file in the same Gist (created aut ``` :::caution -You must use a PAT with `gist` scope — the default `${{ github.token }}` cannot access private gists. +You must use a PAT with gist access — the default `${{ github.token }}` cannot access private gists. Use a classic PAT with `gist` scope, or a fine-grained PAT with **Gists** read/write permission. ::: ## Managing subscribers