Skip to content

fix(changelog): Warn when custom release.yml lacks semver fields #720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BYK merged 1 commit into from
Jan 15, 2026
+884 −413
Merged

fix(changelog): Warn when custom release.yml lacks semver fields #720

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/src/content/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ The command is executed with the following environment variables:
The script should:

- Use these environment variables to perform version replacement
- Replace version occurrences
- Not commit changes
- Not change git state

Expand Down Expand Up @@ -105,6 +106,13 @@ Craft extends GitHub's format with two additional fields:
| `commit_patterns` | Array of regex patterns to match commit/PR titles (in addition to labels) |
| `semver` | Version bump type for auto-versioning: `major`, `minor`, or `patch` |

:::caution[Required for Version Detection]
The `semver` field is required for Craft's automatic version detection to work.
If you define a custom `.github/release.yml` without `semver` fields, PRs will
still appear in the changelog but won't contribute to suggested version bumps.
The [changelog preview](/github-actions/#changelog-preview) will show "None" for semver impact.
:::

#### Default Configuration

If `.github/release.yml` doesn't exist, Craft uses these defaults based on [Conventional Commits](https://www.conventionalcommits.org/):
Expand Down
72 changes: 41 additions & 31 deletions docs/src/content/docs/github-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ For a real-world example of using Craft's GitHub Actions, see the [getsentry/pub

Craft offers two ways to automate releases in GitHub Actions:

| Option | Best For | Flexibility |
|--------|----------|-------------|
| **Reusable Workflow** | Quick setup, standard release flow | Low - runs as a complete job |
| **Composite Action** | Custom workflows, pre/post steps | High - composable with other steps |
| Option | Best For | Flexibility |
| --------------------- | ---------------------------------- | ---------------------------------- |
| **Reusable Workflow** | Quick setup, standard release flow | Low - runs as a complete job |
| **Composite Action** | Custom workflows, pre/post steps | High - composable with other steps |

### Option 1: Reusable Workflow (Recommended)

Expand All @@ -39,27 +39,27 @@ jobs:

#### Workflow Inputs

| Input | Description | Default |
|-------|-------------|---------|
| `version` | Version to release. Can be a semver string (e.g., "1.2.3"), a bump type ("major", "minor", "patch"), or "auto" for automatic detection. | Uses `versioning.policy` from config |
| `merge_target` | Target branch to merge into. | Default branch |
| `force` | Force a release even when there are release-blockers. | `false` |
| `blocker_label` | Label that blocks releases. | `release-blocker` |
| `publish_repo` | Repository for publish issues (owner/repo format). | `{owner}/publish` |
| `git_user_name` | Git committer name. | GitHub actor |
| `git_user_email` | Git committer email. | Actor's noreply email |
| `path` | The path that Craft will run inside. | `.` |
| `craft_config_from_merge_target` | Use the craft config from the merge target branch. | `false` |
| Input | Description | Default |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `version` | Version to release. Can be a semver string (e.g., "1.2.3"), a bump type ("major", "minor", "patch"), or "auto" for automatic detection. | Uses `versioning.policy` from config |
| `merge_target` | Target branch to merge into. | Default branch |
| `force` | Force a release even when there are release-blockers. | `false` |
| `blocker_label` | Label that blocks releases. | `release-blocker` |
| `publish_repo` | Repository for publish issues (owner/repo format). | `{owner}/publish` |
| `git_user_name` | Git committer name. | GitHub actor |
| `git_user_email` | Git committer email. | Actor's noreply email |
| `path` | The path that Craft will run inside. | `.` |
| `craft_config_from_merge_target` | Use the craft config from the merge target branch. | `false` |

#### Workflow Outputs

| Output | Description |
|--------|-------------|
| `version` | The resolved version being released |
| `branch` | The release branch name |
| `sha` | The commit SHA on the release branch |
| Output | Description |
| -------------- | -------------------------------------------- |
| `version` | The resolved version being released |
| `branch` | The release branch name |
| `sha` | The commit SHA on the release branch |
| `previous_tag` | The tag before this release (for diff links) |
| `changelog` | The changelog for this release |
| `changelog` | The changelog for this release |

### Option 2: Composite Action

Expand Down Expand Up @@ -106,7 +106,7 @@ When using auto-versioning, Craft analyzes conventional commits to determine the
name: Auto Release
on:
schedule:
- cron: '0 10 * * 1' # Every Monday at 10 AM
- cron: '0 10 * * 1' # Every Monday at 10 AM

jobs:
release:
Expand Down Expand Up @@ -142,8 +142,8 @@ jobs:

### Inputs

| Input | Description | Default |
|-------|-------------|---------|
| Input | Description | Default |
| --------------- | ----------------------------------------- | -------- |
| `craft-version` | Version of Craft to use (tag or "latest") | `latest` |

### Pinning a Specific Version
Expand All @@ -157,7 +157,7 @@ jobs:
changelog-preview:
uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
with:
craft-version: "2.15.0"
craft-version: '2.15.0'
secrets: inherit
```

Expand All @@ -171,6 +171,12 @@ jobs:
6. **Posts a comment** - Creates or updates a comment on the PR with the changelog preview
7. **Auto-updates** - The comment is automatically updated when you update the PR (push commits, edit title/description, or change labels)

:::note
The version bump suggestion requires categories in your `.github/release.yml` to have
`semver` fields defined. Without them, the suggested bump will show as "None".
See [Auto Mode configuration](/configuration/#auto-mode) for details.
:::

### Example Comment

The workflow posts a comment like this:
Expand Down Expand Up @@ -205,6 +211,7 @@ Entries from this PR are highlighted with a left border (blockquote style).
### PR Trigger Types

The workflow supports these PR event types:

- `opened` - When a PR is created
- `synchronize` - When new commits are pushed
- `reopened` - When a closed PR is reopened
Expand All @@ -216,13 +223,16 @@ The workflow supports these PR event types:
The workflow requires specific permissions and secrets to function correctly:

**Permissions** (required):

- `contents: read` - Allows the workflow to checkout your repository and read git history for changelog generation
- `pull-requests: write` - Allows the workflow to post and update comments on pull requests

**Secrets**:

- `secrets: inherit` - Passes your repository's `GITHUB_TOKEN` to the workflow, ensuring it has access to your repository (especially important for private repositories)

**Repository Setup**:

- The repository should have a git history with tags for the changelog to be meaningful

:::note[Why are these permissions needed?]
Expand All @@ -248,13 +258,13 @@ You can configure labels to exclude PRs from the changelog. In your `.craft.yml`
```yaml
changelog:
categories:
- title: "New Features ✨"
labels: ["feature", "enhancement"]
- title: "Bug Fixes 🐛"
labels: ["bug", "fix"]
- title: 'New Features ✨'
labels: ['feature', 'enhancement']
- title: 'Bug Fixes 🐛'
labels: ['bug', 'fix']
exclude:
labels: ["skip-changelog", "dependencies"]
authors: ["dependabot[bot]", "renovate[bot]"]
labels: ['skip-changelog', 'dependencies']
authors: ['dependabot[bot]', 'renovate[bot]']
```

PRs with the `skip-changelog` label or from excluded authors will not appear in the changelog.
Expand Down
Loading
Loading