getsentry · BYK · Jan 28, 2026 · Jan 28, 2026
diff --git a/docs/src/content/docs/getting-started.md b/docs/src/content/docs/getting-started.md
@@ -54,22 +54,22 @@ This command creates a new release branch, checks the changelog entries, runs a
 
 **Version Specification**
 
-The `NEW-VERSION` argument can be specified in three ways:
+The `NEW-VERSION` argument can be specified in three ways (or omitted to use `auto`):
 
 1. **Explicit version** (e.g., `1.2.3`): Release with the specified version
 2. **Bump type** (`major`, `minor`, or `patch`): Automatically increment the latest tag
-3. **Auto** (`auto`): Analyze commits since the last tag and determine bump type from conventional commit patterns
+3. **Auto** (`auto` or omit the argument): Analyze commits since the last tag and determine bump type from conventional commit patterns
 
 ```shell
-craft prepare NEW-VERSION
+craft prepare [NEW-VERSION]
 
 🚢 Prepare a new release branch
 
 Positionals:
   NEW-VERSION  The new version to release. Can be: a semver string (e.g.,
                "1.2.3"), a bump type ("major", "minor", or "patch"), or "auto"
-               to determine automatically from conventional commits.
-                                                             [string] [required]
+               to determine automatically from conventional commits. When
+               omitted, defaults to "auto".                            [string]
 
 Options:
   --no-input       Suppresses all user prompts                  [default: false]

diff --git a/docs/src/content/docs/github-actions.md b/docs/src/content/docs/github-actions.md
@@ -133,6 +133,7 @@ on:
 permissions:
   contents: read
   pull-requests: write
+  statuses: write
 
 jobs:
   changelog-preview:
@@ -183,14 +184,6 @@ jobs:
 - Multiple updates trigger multiple notifications
 - Can clutter PR conversation on active branches
 
-**Required permissions:**
-
-```yaml
-permissions:
-  contents: read
-  pull-requests: write
-```
-
 #### Status Check Mode
 
 Creates a commit status with the semver impact and writes the full changelog to the Actions job summary:
@@ -216,14 +209,6 @@ jobs:
 - Requires clicking through to Actions run to see full changelog
 - Less immediate visibility than comment
 
-**Required permissions:**
-
-```yaml
-permissions:
-  contents: read
-  statuses: write
-```
-
 :::tip
 Craft itself uses status check mode to avoid notification noise. You can see it in action on any PR in the [getsentry/craft repository](https://github.com/getsentry/craft/pulls).
 :::
@@ -238,6 +223,7 @@ on:
 permissions:
   contents: read
   pull-requests: write
+  statuses: write
 
 jobs:
   changelog-preview:
@@ -308,11 +294,18 @@ The workflow supports these PR event types:
 
 The workflow requires specific permissions and secrets to function correctly:
 
-**Permissions** (required):
+**Permissions** (all three required):
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+```
 
 - `contents: read` - Allows the workflow to checkout your repository and read git history for changelog generation
-- `pull-requests: write` - Required for comment mode (default) to post and update comments on pull requests
-- `statuses: write` - Required for status check mode (when `comment: false`) to create commit statuses
+- `pull-requests: write` - Required for comment mode to post and update comments on pull requests
+- `statuses: write` - Required for status check mode to create commit statuses
 
 **Secrets**:
 
@@ -322,10 +315,8 @@ The workflow requires specific permissions and secrets to function correctly:
 
 - The repository should have a git history with tags for the changelog to be meaningful
 
-:::note[Why are these permissions needed?]
-GitHub Actions reusable workflows use permission intersection - the final permissions are the intersection of what the caller grants and what the workflow declares. By explicitly declaring these permissions in your workflow file, you ensure the workflow can access your repository and perform the necessary actions, even for private repositories.
-
-Note: You only need `pull-requests: write` for comment mode OR `statuses: write` for status check mode, not both. However, it's safe to grant both permissions if you're unsure which mode you'll use.
+:::caution[All permissions are required]
+GitHub Actions reusable workflows use permission intersection - the final permissions are the intersection of what the caller grants and what the workflow declares. The changelog-preview workflow declares both `pull-requests: write` and `statuses: write`, so **your caller workflow must grant both permissions** regardless of which mode you use. If either permission is missing, GitHub will refuse to run the workflow.
 :::
 
 ## Skipping Changelog Entries
@@ -374,6 +365,7 @@ on:
 permissions:
   contents: read
   pull-requests: write
+  statuses: write
 
 jobs:
   changelog-preview:

diff --git a/docs/src/content/docs/targets/aws-lambda-layer.md b/docs/src/content/docs/targets/aws-lambda-layer.md
@@ -12,9 +12,13 @@ Creates a new public Lambda layer in each available AWS region and updates the S
 | `layerName` | Name of the Lambda layer. Supports template variables (see below) |
 | `compatibleRuntimes` | List of runtime configurations |
 | `license` | Layer license |
-| `linkPrereleases` | Update for preview releases. Default: `false` |
+| `linkPrereleases` | Publish layers for preview/pre-release versions. Default: `false` |
 | `includeNames` | Must filter to exactly one artifact |
 
+:::note[Pre-release Versions]
+Layer publication is automatically skipped for pre-release versions (e.g., `1.0.0-alpha.1`, `2.0.0-rc.1`) unless `linkPrereleases` is set to `true`. This prevents unstable versions from being published to all AWS regions.
+:::
+
 ### Layer Name Templating
 
 The `layerName` option supports Mustache-style template variables for dynamic version interpolation:

diff --git a/docs/src/content/docs/targets/brew.md b/docs/src/content/docs/targets/brew.md
@@ -15,9 +15,13 @@ Formulas on `homebrew/core` are not supported. Use your own tap repository.
 |--------|-------------|
 | `tap` | Homebrew tap name (e.g., `octocat/tools` → `github.com:octocat/homebrew-tools`) |
 | `template` | Formula template (Ruby code) with Mustache interpolation |
-| `formula` | Formula name. Default: repository name |
+| `formula` | Formula name (supports Mustache templating with `{{version}}`). Default: repository name |
 | `path` | Path to store formula. Default: `Formula` |
 
+:::note[Pre-release Versions]
+The Brew target automatically skips pre-release versions (e.g., `1.0.0-alpha.1`, `2.0.0-rc.1`). Homebrew formulas are only updated for stable releases.
+:::
+
 ### Template Variables
 
 - `version`: The new version

diff --git a/docs/src/content/docs/targets/docker.md b/docs/src/content/docs/targets/docker.md
@@ -39,14 +39,20 @@ Copies an existing source image tagged with the revision SHA to a new target tag
 
 1. Explicit `usernameVar`/`passwordVar` from config
 2. Registry-derived: `DOCKER_<REGISTRY>_USERNAME/PASSWORD` (e.g., `DOCKER_GHCR_IO_USERNAME`)
-3. Built-in defaults for `ghcr.io`: `GITHUB_ACTOR` and `GITHUB_TOKEN`
+3. Built-in defaults for `ghcr.io`: `GITHUB_ACTOR` (or `x-access-token`) and `GITHUB_TOKEN` (or `GITHUB_API_TOKEN`)
 4. Fallback: `DOCKER_USERNAME` and `DOCKER_PASSWORD`
 
 | Name | Description |
 |------|-------------|
 | `DOCKER_USERNAME` | Default username for target registry |
 | `DOCKER_PASSWORD` | Default password/token for target registry |
 | `DOCKER_BIN` | Path to `docker` executable |
+| `GITHUB_TOKEN` | Used for `ghcr.io` authentication (with `GITHUB_ACTOR` as username) |
+| `GITHUB_API_TOKEN` | Alternative to `GITHUB_TOKEN` for `ghcr.io` (uses `x-access-token` as username) |
+
+:::tip[GitHub Container Registry]
+For `ghcr.io`, Craft automatically uses GitHub Actions environment variables. If `GITHUB_TOKEN` is not available, it falls back to `GITHUB_API_TOKEN` with `x-access-token` as the username, which works with GitHub App installation tokens and PATs.
+:::
 
 ## Examples