From fb47fe643a8d8e64e1ca73c80e2a65934573d996 Mon Sep 17 00:00:00 2001
From: Jack Sullivan <jack@divergent.codes>
Date: Thu, 30 Jul 2026 12:43:19 -0700
Subject: [PATCH] docs: document org setup for private cross-repo use

Using this action from another DivergentCodes repository needs two settings
that are not discoverable from the code, and getting either wrong produces
an error that does not say what is missing: the action repo must allow
organization-wide access, and a token that can read DivergentCodes/commitlint
must be supplied, because the default github.token is scoped to the calling
repository and cannot read a different private repo.

Add a section covering both, with a copy-pasteable workflow and a
troubleshooting list mapping each symptom to the setting that causes it.
Both README workflow examples were extracted and checked with actionlint.

Refresh version references that named tags older than what is published.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VSrrciEDBTuFNMtKocScML
---
 README.md  | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 action.yml |  2 +-
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 933a3ac..8891e7e 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ merge with rebase or merge commits instead, set `commits-mode: block`.
 
 | Input | Default | Meaning |
 |---|---|---|
-| `version` | `latest` | commitlint version to `go install`; pin a tag (e.g. `v1.0.0`) in production |
+| `version` | `latest` | commitlint version to `go install`; pin a tag (e.g. `v1.1.2`) in production |
 | `pr-title-mode` | `block` | `block` fails the check, `warn` reports only, `off` skips |
 | `commits-mode` | `warn` | same modes, applied to each PR commit |
 | `types` | conventional set | comma-separated allowed types |
@@ -82,6 +82,56 @@ bypassed. Pass a token that can read that repo:
 
 Once `commitlint` is public this is unnecessary and the default applies.
 
+## Using this in another DivergentCodes repository
+
+Both repositories are private, which needs two one-time settings. Neither has
+to be made public.
+
+**1. Let other org repos use this action.** Private actions are not callable
+across repositories by default. In **this** repo: Settings → Actions → General
+→ Access → *Accessible from repositories in the DivergentCodes organization*.
+Without it, consuming workflows fail before the action runs.
+
+**2. Provide a token that can read `DivergentCodes/commitlint`.** The default
+`github.token` is scoped to the repository running the workflow, so it cannot
+read a *different* private repo. Create a fine-grained PAT (or GitHub App
+token) with **Contents: read** on `DivergentCodes/commitlint` only, and add it
+as an organization secret named `COMMITLINT_READ_TOKEN`.
+
+Then, in the consuming repository:
+
+```yaml
+name: pr-lint
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+permissions:
+  contents: read
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@<full-sha>
+      - uses: DivergentCodes/commitlint-action@<full-sha>  # v1.0.1
+        with:
+          github-token: ${{ secrets.COMMITLINT_READ_TOKEN }}
+          pr-title-mode: block
+          commits-mode: warn
+```
+
+If `commitlint` later becomes public, drop the `github-token` line and delete
+the secret; nothing else changes.
+
+### Troubleshooting org setup
+
+- **`terminal prompts disabled`** during *Install commitlint* → the token is
+  missing, expired, or lacks Contents: read on `DivergentCodes/commitlint`.
+- **The workflow fails before any step runs**, with a message about the
+  action not being found → step 1 above has not been applied.
+- **`could not read Username`** with a token set → the secret is defined in
+  the wrong scope; organization secrets must be made visible to the consuming
+  repository.
+
 ## Runner requirements
 
 Runs on `ubuntu-latest` (and other GitHub-hosted runners) out of the box: it
diff --git a/action.yml b/action.yml
index 37f4989..cefa2aa 100644
--- a/action.yml
+++ b/action.yml
@@ -11,7 +11,7 @@ branding:
 
 inputs:
   version:
-    description: commitlint version to install (a tag like v1.1.0, or latest)
+    description: commitlint version to install (a tag like v1.1.2, or latest)
     default: latest
   pr-title-mode:
     description: "Lint the PR title: block | warn | off"