Skip to content

Add native sticky PR comment infrastructure for changelog validation #3993

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
Mpdreamz merged 3 commits into from
Sep 1, 2026
Merged

Add native sticky PR comment infrastructure for changelog validation #3993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f49f7a1
Drop mode: gh-release from changelog-publish — now auto-detected
Mpdreamz Aug 31, 2026
52b9888
Add native sticky PR comment infrastructure for changelog validation
Mpdreamz Sep 1, 2026
d390472
Merge branch 'main' into feature/changelog-pr-comment-native
Mpdreamz Sep 1, 2026
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
215 changes: 214 additions & 1 deletion docs/cli-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3690,6 +3690,33 @@
"summary": "Bot login name for loop detection",
"defaultValue": "github-actions[bot]"
},
{
"role": "flag",
"name": "is-fork",
"type": "boolean",
"required": false,
"defaultValue": "false"
},
{
"role": "flag",
"name": "can-commit",
"type": "boolean",
"required": false,
"defaultValue": "false"
},
{
"role": "flag",
"name": "maintainer-can-modify",
"type": "boolean",
"required": false,
"defaultValue": "false"
},
{
"role": "flag",
"name": "head-repo",
"type": "string",
"required": false
},
{
"role": "flag",
"name": "log-level",
Expand Down Expand Up @@ -3851,6 +3878,139 @@
}
]
},
{
"path": [
"changelog"
],
"name": "github-comment",
"summary": "(CI, hidden) Post or update the sticky changelog comment on the PR.",
"notes": "Reads the decision metadata and renders the appropriate body based on the validation status\nand commit outcome. Owner and repo are resolved from the GITHUB_REPOSITORY environment\nvariable (always set by GitHub Actions). This command is only meaningful under\nGITHUB_ACTIONS and must only be invoked from a job with pull-requests: write.",
"usage": "docs-builder changelog github-comment --metadata \u003Cstring\u003E",
"examples": [],
"parameters": [
{
"role": "flag",
"name": "metadata",
"type": "string",
"required": true,
"summary": "Path to the decision metadata.json file"
},
{
"role": "flag",
"name": "log-level",
"shortName": "l",
"type": "enum",
"required": false,
"summary": "Minimum log level. Default: information",
"enumValues": [
"trace",
"debug",
"information",
"warning",
"error",
"critical",
"none"
]
},
{
"role": "flag",
"name": "config-source",
"shortName": "c",
"type": "enum",
"required": false,
"summary": "Override the configuration source: local, remote",
"enumValues": [
"local",
"remote",
"embedded"
]
},
{
"role": "flag",
"name": "skip-private-repositories",
"type": "boolean",
"required": false,
"summary": "Skip cloning private repositories"
}
],
"hidden": true
},
{
"path": [
"changelog"
],
"name": "github-decision",
"summary": "(CI, hidden) Record commit outcome into the decision metadata file.",
"notes": "Reads metadata.json, amends it with the commit step result, and writes it back.\nRun by submit/apply after the git-push step so the downstream\nchangelog github-comment command knows which body to render.",
"usage": "docs-builder changelog github-decision --metadata \u003Cstring\u003E --commit-outcome \u003Cenum\u003E [options]",
"examples": [],
"parameters": [
{
"role": "flag",
"name": "metadata",
"type": "string",
"required": true,
"summary": "Path to the decision metadata.json file"
},
{
"role": "flag",
"name": "commit-outcome",
"type": "enum",
"required": true,
"summary": "Outcome of the changelog commit step",
"enumValues": [
"none",
"committed",
"failed"
]
},
{
"role": "flag",
"name": "committed-file",
"type": "string",
"required": false,
"summary": "Repo-relative path to the committed file (when commitOutcome is Committed)"
},
{
"role": "flag",
"name": "log-level",
"shortName": "l",
"type": "enum",
"required": false,
"summary": "Minimum log level. Default: information",
"enumValues": [
"trace",
"debug",
"information",
"warning",
"error",
"critical",
"none"
]
},
{
"role": "flag",
"name": "config-source",
"shortName": "c",
"type": "enum",
"required": false,
"summary": "Override the configuration source: local, remote",
"enumValues": [
"local",
"remote",
"embedded"
]
},
{
"role": "flag",
"name": "skip-private-repositories",
"type": "boolean",
"required": false,
"summary": "Skip cloning private repositories"
}
],
"hidden": true
},
{
"path": [
"changelog"
Expand Down Expand Up @@ -4898,7 +5058,7 @@
"name": "validate-labels",
"summary": "(CI) Validate PR labels against the changelog config without writing any files or calling the GitHub API.",
"notes": "A lightweight label-only gate intended for the pull_request event. Resolves\npivot.types, pivot.products, and rules.create skip labels against the PR\u0027s\nlabel set and exits non-zero on no-label. Does not perform title resolution, bot-loop\ndetection, or changelog-file lookup \u2014 use EvaluatePr when those are needed.\n\n\nOutputs: status (ok | no-label | skipped), type, products,\nlabel-table (shown on failure), product-label-table (shown on product failure),\nskip-labels.",
"usage": "docs-builder changelog validate-labels --config \u003Cfile\u003E --pr-labels \u003Cstring\u003E",
"usage": "docs-builder changelog validate-labels --config \u003Cfile\u003E --pr-labels \u003Cstring\u003E [options]",
"examples": [],
"parameters": [
{
Expand All @@ -4924,6 +5084,59 @@
"required": true,
"summary": "Comma-separated list of PR labels (use ${{ join(github.event.pull_request.labels.*.name, \u0027,\u0027) }} in actions)."
},
{
"role": "flag",
"name": "pr-number",
"type": "integer",
"required": false,
"summary": "PR number \u2014 required for decision metadata written when running on CI.",
"defaultValue": "0"
},
{
"role": "flag",
"name": "head-ref",
"type": "string",
"required": false,
"summary": "PR head branch ref \u2014 written to decision metadata when on CI."
},
{
"role": "flag",
"name": "head-sha",
"type": "string",
"required": false,
"summary": "PR head commit SHA \u2014 written to decision metadata when on CI."
},
{
"role": "flag",
"name": "is-fork",
"type": "boolean",
"required": false,
"summary": "Whether the PR is from a fork.",
"defaultValue": "false"
},
{
"role": "flag",
"name": "can-commit",
"type": "boolean",
"required": false,
"summary": "Whether the commit strategy allows committing.",
"defaultValue": "false"
},
{
"role": "flag",
"name": "maintainer-can-modify",
"type": "boolean",
"required": false,
"summary": "Whether the fork PR allows maintainer edits.",
"defaultValue": "false"
},
{
"role": "flag",
"name": "head-repo",
"type": "string",
"required": false,
"summary": "Fork repository full name (owner/repo)."
},
{
"role": "flag",
"name": "log-level",
Expand Down
2 changes: 2 additions & 0 deletions docs/cli/changelog/cmd-evaluate-pr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ This command is intended for CI automation. It is used internally by the changel

Evaluate a pull request for changelog generation eligibility. Performs pre-flight checks (body-only edit, bot loop detection, manual edit detection), loads the changelog configuration, checks label-based creation rules, resolves the PR title and type, and sets GitHub Actions outputs for downstream steps.

When running under GitHub Actions (the `GITHUB_ACTIONS` environment variable is set), the command writes a decision metadata file to `.artifacts/changelog-decision/metadata.json`. This file is picked up by the downstream `changelog github-comment` command to post or update the sticky PR comment. Pass `--is-fork`, `--can-commit`, and `--maintainer-can-modify` so the comment command can select the correct comment body for fork and comment-only PR strategies.

## GitHub Actions outputs

| Output | Description |
Expand Down
11 changes: 10 additions & 1 deletion docs/cli/changelog/cmd-validate-labels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Validate that a pull request's labels contain a recognised changelog type label,

Exits non-zero when `status` is `no-label`. All other statuses (`ok`, `skipped`) exit zero.

When running under GitHub Actions (the `GITHUB_ACTIONS` environment variable is set) and `--pr-number` is provided, the command writes a decision metadata file to `.artifacts/changelog-decision/metadata.json`. This file is picked up by the downstream `changelog github-comment` command to post or update the sticky PR comment.

## GitHub Actions outputs

| Output | Description |
Expand All @@ -19,10 +21,17 @@ Exits non-zero when `status` is `no-label`. All other statuses (`ok`, `skipped`)
| `product-label-table` | Markdown table of configured label-to-product mappings (when `no-label` due to missing product) |
| `skip-labels` | Comma-separated list of configured skip labels (from `rules.create` exclude rules) |

## Decision metadata

When `--pr-number` is supplied and the command runs under GitHub Actions, it writes `.artifacts/changelog-decision/metadata.json` relative to the checkout root. The file contains the PR number, head ref/SHA, validation status, and label tables. A consumer workflow uploads this file as the `changelog-decision` artifact and a `workflow_run` job picks it up to call `changelog github-comment`.

## Examples

```sh
docs-builder changelog validate-labels \
--config docs/changelog.yml \
--pr-labels "enhancement,Team:Core"
--pr-labels "enhancement,Team:Core" \
--pr-number 42 \
--head-ref feature-branch \
--head-sha abc123
```
7 changes: 2 additions & 5 deletions src/services/Elastic.Changelog/Evaluation/ChangelogArtifactEvaluationService.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,11 @@ IRunnerTempFileSystem fileSystem

public async Task<bool> EvaluateArtifact(IDiagnosticsCollector collector, EvaluateArtifactArguments input, Cancel ctx)
{
ChangelogArtifactMetadata? metadata;
GithubDecisionMetadata? metadata;
try
{
var artifactMetadataJson = await _fileSystem.File.ReadAllTextAsync(input.MetadataPath, ctx);
metadata = JsonSerializer.Deserialize(
artifactMetadataJson,
ChangelogArtifactMetadataJsonContext.Default.ChangelogArtifactMetadata
);
metadata = JsonSerializer.Deserialize(artifactMetadataJson, GithubDecisionMetadataJsonContext.Default.GithubDecisionMetadata);
}
catch (FileNotFoundException)
{
Expand Down
36 changes: 0 additions & 36 deletions src/services/Elastic.Changelog/Evaluation/ChangelogArtifactMetadata.cs
View file
Open in desktop

This file was deleted.

Loading
Loading