From f07593ece599a91badf0e2743620407c82195d96 Mon Sep 17 00:00:00 2001 From: Burak Yigit Kaya Date: Wed, 28 Jan 2026 12:56:14 +0000 Subject: [PATCH] docs: Update documentation for changes since 2.17.0 - Docker: Add GITHUB_API_TOKEN fallback for ghcr.io authentication - AWS Lambda Layer: Document pre-release version skipping behavior - Getting Started: Update craft prepare to show NEW-VERSION as optional - Brew: Add notes about pre-release skipping and formula templating - GitHub Actions: Fix changelog-preview permissions (both pull-requests and statuses write permissions are always required) --- docs/src/content/docs/getting-started.md | 10 ++--- docs/src/content/docs/github-actions.md | 38 ++++++++----------- .../content/docs/targets/aws-lambda-layer.md | 6 ++- docs/src/content/docs/targets/brew.md | 6 ++- docs/src/content/docs/targets/docker.md | 8 +++- 5 files changed, 37 insertions(+), 31 deletions(-) diff --git a/docs/src/content/docs/getting-started.md b/docs/src/content/docs/getting-started.md index 2afef2c7..4ac03d82 100644 --- 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 index 8429511b..3984f6b3 100644 --- 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 index ce3345ae..75c4ef60 100644 --- 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 index dd62567f..7f3246fb 100644 --- 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 index 9c6aac50..cef490cf 100644 --- a/docs/src/content/docs/targets/docker.md +++ b/docs/src/content/docs/targets/docker.md @@ -39,7 +39,7 @@ 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__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 | @@ -47,6 +47,12 @@ Copies an existing source image tagged with the revision SHA to a new target tag | `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