From a82b3cffb12672c24cd355986f0bc62dde1311d4 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 8 Mar 2026 16:56:52 +0000 Subject: [PATCH] docs: gist store requires classic PAT, not fine-grained Fine-grained PATs do not support gist API access despite listing a "Gists" permission. Correct all docs to specify classic PAT (ghp_) with gist scope. Reverts the incorrect fine-grained guidance from #124. Co-Authored-By: Claude Opus 4.6 --- .github/actions/send-file/action.yml | 2 +- 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 | 13 +++++++------ 5 files changed, 12 insertions(+), 11 deletions(-) diff --git a/.github/actions/send-file/action.yml b/.github/actions/send-file/action.yml index b7c0baa..69e57d1 100644 --- a/.github/actions/send-file/action.yml +++ b/.github/actions/send-file/action.yml @@ -48,7 +48,7 @@ inputs: description: Gist ID for subscriber storage (required when subscriber-store is gist) required: false github-token: - description: GitHub PAT with gist scope (required when subscriber-store is gist) + description: Classic PAT with gist scope (fine-grained PATs don't work; required when subscriber-store is gist) required: false audience: description: Audience ID for multi-audience products diff --git a/README.md b/README.md index f06e4d4..80f64b3 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` | 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) | +| `GITHUB_TOKEN` | Classic PAT with `gist` scope (fine-grained PATs do not support gists; 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 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 +3. Create a [classic PAT](https://github.com/settings/tokens/new) with `gist` scope (fine-grained PATs don't work with gists) 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 f91871f..c07e8bd 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` | 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) | +| `GITHUB_TOKEN` | Classic PAT with `gist` scope (fine-grained PATs do not support gists; 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 7daebc1..deb804d 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 access (classic: gist scope; fine-grained: Gists read/write) +GITHUB_TOKEN=ghp_your_pat # classic PAT with gist scope (fine-grained PATs don't work) ``` 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 dcb3875..61d1bfa 100644 --- a/site/src/content/docs/subscriber-stores/gist.mdx +++ b/site/src/content/docs/subscriber-stores/gist.mdx @@ -21,12 +21,13 @@ 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 access +### 2. Create a classic PAT with `gist` scope -The default `GITHUB_TOKEN` in Actions is scoped to the repository and **cannot access private gists**. Create one of: +The default `GITHUB_TOKEN` in Actions is scoped to the repository and **cannot access private gists**. Create a [classic PAT](https://github.com/settings/tokens/new) and check the **gist** scope. -- **[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 +:::note +You must use a **classic** PAT (starts with `ghp_`). Fine-grained PATs do not support gist API access. +::: ### 3. Add repository secrets @@ -48,7 +49,7 @@ export GITHUB_TOKEN=ghp_your_pat_here | Variable | Required | Description | |---|---|---| | `GITHUB_GIST_ID` | Yes | ID of the private Gist | -| `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) | +| `GITHUB_TOKEN` | Yes | Classic PAT with `gist` scope (fine-grained PATs do not support gists; the default Actions token cannot access private gists) | ## File format @@ -98,7 +99,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 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. +You must use a **classic** PAT with `gist` scope — fine-grained PATs do not support gists, and the default `${{ github.token }}` cannot access private gists. ::: ## Managing subscribers