diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 41ea87d..f6a9e15 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "1.2.1" + ".": "1.2.2" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 89982fc..cdbad6e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,13 @@ All notable changes to leash-secrets will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.2.2](https://github.com/FasterApiWeb/leash-secrets/compare/leash-secrets-v1.2.1...leash-secrets-v1.2.2) (2026-07-10) + +### Maintenance + +* release 1.2.2 + ## [1.2.1](https://github.com/FasterApiWeb/leash-secrets/compare/leash-secrets-v1.2.0...leash-secrets-v1.2.1) (2026-07-09) diff --git a/CITATION.cff b/CITATION.cff index ffcdc2b..f8c0ca0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -12,8 +12,8 @@ authors: repository-code: https://github.com/FasterApiWeb/leash-secrets url: https://fasterapiweb.github.io/leash-secrets license: MIT -version: 1.2.1 -date-released: "2026-07-09" +version: 1.2.2 +date-released: "2026-07-10" keywords: - secret-detection - security diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 957e7b1..2ec12fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -93,20 +93,27 @@ Quick path: **Actions → Release Draft (auto-bumps) → Publish draft → npm** ### One-time secrets +Prefer **org-level** secrets (not a personal PAT): + | Secret | Purpose | |--------|---------| | `NPM_TOKEN` | Publish to npm (**required** to ship) | -| `RELEASE_TOKEN` or `RELEASE_APP_*` | Recommended for Release Draft push to protected `main` (else `GITHUB_TOKEN` may be blocked) | +| `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` / `RELEASE_APP_INSTALLATION_ID` | Org GitHub App so Release Draft can push bumps to protected `main` | | `VSCE_PAT` | VS Code marketplace *(deferred)* | -Details: [ci-cd.md — Secrets](docs/contributing/ci-cd.md#secrets-needed). +Do **not** use a personal `RELEASE_TOKEN` if the App is set up. Full steps (create App, install, secrets, ruleset bypass): [ci-cd.md — Org GitHub App](docs/contributing/ci-cd.md#org-github-app-for-release-draft-recommended). **No CI workflow file changes** are required for the App. + +### After merge to `main` + +Automatic: **CI** (always) → **Validate Patterns** / **Deploy Docs** (only if paths match) → **Release** (legacy; ignore). +To ship: **Release Draft** → Publish draft → **Publish npm**. Details: [ci-cd.md — After a merge](docs/contributing/ci-cd.md#after-a-merge-to-main--what-runs-in-order). ### Release checklist (short) 1. **Actions → Release Draft → Run** (`patch` / `minor` / `major`) — bumps version on `main` if needed, creates draft 2. **Releases → Publish** the draft → **Publish npm** runs (skips if version already on npm) -If the draft push fails: add `RELEASE_TOKEN` (admin PAT / bypass) and re-run. +If the draft push fails: finish org App + ruleset bypass, then re-run. If you only need npm: **Actions → Publish npm → Run workflow**. ## PR Guidelines diff --git a/docs/contributing/ci-cd.md b/docs/contributing/ci-cd.md index c19f0ce..fcb851c 100644 --- a/docs/contributing/ci-cd.md +++ b/docs/contributing/ci-cd.md @@ -13,7 +13,8 @@ You open a PR Push lands on main → CI again - → Deploy Docs + → Deploy Docs (if docs/** changed) + → Validate Patterns (if patterns/** changed) → Release (release-please) ← legacy; usually ignore When you want to ship a version @@ -40,42 +41,133 @@ Release Draft (auto-bump) → draft tag/assets → Publish draft → npm | Workflow | When it runs | Purpose | |----------|--------------|---------| -| **CI** | Every PR + every push to `main` | Quality gate: Node 18/20/22 tests, shell syntax, hygiene (incl. `install.sh` ↔ `package.json` version), dogfood scan | -| **Validate Patterns** | PRs/pushes that touch `patterns/` | Pattern JSON / fixture validation | -| **Deploy Docs** | Push to `main` | MkDocs → GitHub Pages | -| **Release** (release-please) | Push to `main` | **Legacy.** Tries to manage release PRs/tags. Org often blocks Actions from opening PRs — prefer **Release Draft** | -| **Release Draft** | **Manual** (`workflow_dispatch`) | You pick patch/minor/major → bumps `package.json` / `install.sh` / etc. if needed → **draft** `leash-secrets-vX.Y.Z` + assets | +| **CI** | Every PR + every push to `main` (+ manual) | Quality gate: Node 18/20/22 tests, shell syntax, hygiene (incl. `install.sh` ↔ `package.json` version), dogfood scan | +| **Validate Patterns** | PRs/pushes that touch `patterns/` (or related tests/scripts) | Pattern JSON / fixture validation | +| **Deploy Docs** | Push to `main` that touches `docs/**` (or MkDocs config) (+ manual) | MkDocs → GitHub Pages | +| **Release** (release-please) | Push to `main` (+ manual) | **Legacy.** Tries to manage release PRs/tags. Org often blocks Actions from opening PRs — prefer **Release Draft** | +| **Release Draft** | **Manual** (`workflow_dispatch`) | You pick patch/minor/major → bumps version files if needed → **draft** `leash-secrets-vX.Y.Z` + assets | | **Publish npm** | Manual, **or** when a draft release is **published** | `npm publish --provenance` (succeeds as no-op if version already on npm) | Workflow files live under [`.github/workflows/`](https://github.com/FasterApiWeb/leash-secrets/tree/main/.github/workflows). +## After a merge to `main` — what runs, in order + +Merging a PR (or landing a commit on `main`) does **not** publish npm. These workflows fire automatically from the push: + +| Order | Workflow | Runs when? | What it does | You should… | +|-------|----------|------------|--------------|-------------| +| 1 | **CI** | Always on push to `main` | Re-runs the full test matrix on `main` | Wait for green. Required status check for future PRs. | +| 2 | **Validate Patterns** | Only if the merge touched `patterns/**`, `tests/**`, or `scripts/check-patterns.js` | Extra pattern/fixture checks | Confirm green if it ran; otherwise ignore. | +| 3 | **Deploy Docs** | Only if the merge touched `docs/**`, `mkdocs.yml`, `requirements.txt`, or the docs workflow | Builds MkDocs and deploys GitHub Pages | Confirm the site updated if you changed docs. | +| 4 | **Release** (release-please) | Always on push to `main` | Legacy release-please attempt | **Ignore** unless debugging. Prefer **Release Draft** to ship. | + +Nothing else is required for a normal feature/fix merge. + +### When you want to ship a version (manual, after `main` is green) + +Do these **in order** — they are not automatic on merge: + +| Order | Action | Workflow / UI | Purpose | +|-------|--------|---------------|---------| +| 1 | Run **Release Draft** | Actions → Release Draft → patch/minor/major | Bumps version on `main` (needs org GitHub App; see below), creates **draft** `leash-secrets-vX.Y.Z` | +| 2 | Review & **Publish** the draft | Releases → open draft → Publish | Makes the GitHub Release public; fires the next step | +| 3 | **Publish npm** | Runs automatically on publish (or Actions → Publish npm) | Publishes `leash-secrets@X.Y.Z` (skips if already on npm) | + +Optional: **Publish npm** alone if the GitHub release/tag already exists and you only need the registry. + ## Secrets needed -Add under **Settings → Secrets and variables → Actions**. +Prefer **org-level** secrets (FasterApiWeb → Settings → Secrets and variables → Actions → Organization secrets) so nothing is tied to a personal account. Grant them to `leash-secrets` (and any other repos that release the same way). | Secret | Required? | Used by | How to create | |--------|-----------|---------|---------------| | `NPM_TOKEN` | **Yes** (to publish) | Publish npm | [npmjs.com](https://www.npmjs.com) → Access Tokens → Granular token with **Read and Write** + **Bypass 2FA for publish** | -| `RELEASE_TOKEN` | Optional | Release Draft | PAT with contents write; otherwise `GITHUB_TOKEN` is used | -| `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` / `RELEASE_APP_INSTALLATION_ID` | Optional | Release Draft | GitHub App install token (same pattern as fork-shepherd releases) | +| `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` / `RELEASE_APP_INSTALLATION_ID` | **Recommended** | Release Draft | Org GitHub App (see below). Preferred over a personal PAT. | +| `RELEASE_TOKEN` | Avoid | Release Draft | Personal PAT — not needed if the App is configured | | `VSCE_PAT` | Deferred | VS Code extension publish | Azure DevOps PAT with **Marketplace → Manage** | -### Actions policy +### Org GitHub App for Release Draft (recommended) + +`GITHUB_TOKEN` cannot push to protected `main`. A **personal** `RELEASE_TOKEN` works but is tied to one human. Use an **org-owned GitHub App** instead. **No workflow file changes are required** — `release-draft.yml` already reads these secrets. + +#### 1. Create the App (org owner) + +1. Open [github.com/organizations/FasterApiWeb/settings/apps/new](https://github.com/organizations/FasterApiWeb/settings/apps/new) +2. Fill in: + - **GitHub App name:** e.g. `FasterApiWeb Release` (must be unique on GitHub) + - **Homepage URL:** `https://github.com/FasterApiWeb` (or this repo’s URL) + - **Webhook:** uncheck **Active** +3. **Repository permissions:** + - **Contents** → **Read and write** + - **Metadata** → **Read-only** (usually already set) +4. Leave **Account permissions** at **No access** +5. **Where can this GitHub App be installed?** → **Only on this account** +6. Click **Create GitHub App** + +#### 2. Generate the private key + +1. On the App settings page → **Private keys** → **Generate a private key** +2. Download the `.pem` (paste into a secret once; never commit it) +3. Note the **App ID** under **About** (digits only) + +#### 3. Install the App on the org + +1. App settings → **Install App** (or open the App’s install URL) +2. Choose **FasterApiWeb** +3. **Only select repositories** → **`leash-secrets`** (or all repos if you reuse it) +4. **Install** -Org/repo must allow Marketplace actions: +#### 4. Copy the Installation ID -`Settings → Actions → General → Allow all actions and reusable workflows` +1. [Org → Settings → GitHub Apps → Installed GitHub Apps](https://github.com/organizations/FasterApiWeb/settings/installations) → **Configure** next to the App +2. URL looks like: + `https://github.com/organizations/FasterApiWeb/settings/installations/XXXXXXXX` + **`XXXXXXXX`** = `RELEASE_APP_INSTALLATION_ID` -If CI shows `startup_failure` with zero jobs, the org is likely set to `local_only`. +#### 5. Add org Actions secrets + +1. [Organization secrets](https://github.com/organizations/FasterApiWeb/settings/secrets/actions) → **New organization secret** for each: + + | Name | Value | + |------|--------| + | `RELEASE_APP_ID` | App ID (number) | + | `RELEASE_APP_PRIVATE_KEY` | Full `.pem` contents (including `BEGIN` / `END` lines) | + | `RELEASE_APP_INSTALLATION_ID` | Installation ID (number) | + +2. **Repository access** → **Selected repositories** → add **`leash-secrets`** + +Do **not** add a personal `RELEASE_TOKEN` if the App is configured. + +#### 6. Bypass rulesets for the App (required) + +Secrets alone are not enough — branch rules still block pushes unless the App is on the bypass list. + +1. Repo [Rules](https://github.com/FasterApiWeb/leash-secrets/rules) (or org rulesets) → open the ruleset that targets `main` +2. **Bypass list** → **Add bypass** → **GitHub Apps** → select your Release App +3. Bypass mode: **Always allow** (or **Exempt**) +4. Save + +Also check classic **Settings → Branches** protection if it still applies. + +#### 7. Actions policy + +Org or repo: **Settings → Actions → General** → **Allow all actions and reusable workflows** +(needed for `actions/create-github-app-token@v2`) + +#### 8. Verify + +1. **Actions → Release Draft → Run workflow** (`main`, `patch`; optional `dry_run` first) +2. Log step **Resolve release token** should say: `Using GitHub App installation token` +3. On a real run, the bump commit should land on **`main`** (not `release/v*`) + +Release Draft token preference: App → `RELEASE_TOKEN` → `GITHUB_TOKEN`. ## Day-to-day (features / fixes) 1. Open a PR → wait for **CI** (and **Validate Patterns** if you changed patterns). 2. Merge when green (squash). -3. **Deploy Docs** updates the site on `main`. -4. Ignore **Release** (release-please) unless debugging it. - -No npm publish happens on normal merges. +3. On `main`: **CI** always; **Deploy Docs** / **Validate Patterns** only if paths match; ignore **Release**. +4. No npm publish on normal merges. ## How to ship a version @@ -92,7 +184,7 @@ The workflow: - If `package.json` is behind, **bumps** `package.json`, `install.sh`, `CITATION.cff`, `vscode-extension/package.json`, manifest, and `CHANGELOG.md`, then **pushes** `chore: release X.Y.Z` to `main` - Creates a **draft** release `leash-secrets-vX.Y.Z` + assets -If the push fails (branch protection), add `RELEASE_TOKEN` (admin PAT that can push to `main` / bypass rulesets) or allow the GitHub Actions app to bypass the main ruleset, then re-run. +If the push fails (branch protection), finish the org GitHub App + ruleset bypass steps above, then re-run. Without that, the workflow falls back to a `release/vX.Y.Z` branch (merge that to `main` manually, then delete the branch). ### 2. Publish the draft @@ -107,6 +199,7 @@ Result: **Publish npm** runs and publishes `leash-secrets@X.Y.Z` (or no-ops if t **Actions → Publish npm → Run workflow** — publishes whatever version is on the checked-out ref; skips cleanly if already published. Optional local prep (still supported): `bash scripts/prepare-release.sh` if you prefer a version-bump PR before Release Draft. + ## Branch protection (maintainer note) `main` requires PRs and the CI status checks. Required **approving** reviews are set to **0** so the sole maintainer can merge their own PRs (GitHub never counts self-approvals). CI must still be green. Revisit if more maintainers join. diff --git a/package.json b/package.json index c835006..a4c6579 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "leash-secrets", - "version": "1.2.1", + "version": "1.2.2", "description": "Keep your secrets on a leash — AI agent skill that catches exposed API keys, tokens, and credentials before they hit your codebase", "main": "src/index.js", "bin": { diff --git a/scripts/install.sh b/scripts/install.sh index cd3614c..bb8c7fa 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -5,7 +5,7 @@ set -euo pipefail # leash-secrets installer — macOS · Linux · WSL · Git Bash # ────────────────────────────────────────── -VERSION="1.2.1" +VERSION="1.2.2" REPO="FasterApiWeb/leash-secrets" RAW="https://raw.githubusercontent.com/$REPO/main" diff --git a/vscode-extension/package.json b/vscode-extension/package.json index 199e71c..2bc1a82 100644 --- a/vscode-extension/package.json +++ b/vscode-extension/package.json @@ -2,7 +2,7 @@ "name": "leash-secrets-vscode", "displayName": "Leash Secrets — Secret Scanner", "description": "Inline warnings for exposed API keys, tokens, and credentials. 71 patterns across 11 provider categories.", - "version": "1.2.1", + "version": "1.2.2", "publisher": "FasterApiWeb", "license": "MIT", "icon": "icon.png",