ci: optimize git-cliff workflow for automated changelog #117
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Reviewer's GuideOptimizes the CD git-cliff workflow so that it generates both a latest-release snippet and a full docs/changelog.rst file using git-cliff v4, then opens a PR with changelog updates and updates GitHub release notes, instead of pushing directly to main. Sequence diagram for updated git-cliff-based changelog and release flowsequenceDiagram
actor U as "Maintainer"
participant GH as "GitHub (events)"
participant WF as "CD Workflow (cd.yml)"
participant CL1 as "git-cliff action v4 (latest snippet)"
participant GIT as "Git repository (main + worktree)"
participant CL2 as "git-cliff action v4 (full changelog)"
participant GHCLI as "gh CLI"
participant PRS as "GitHub Pull Requests"
participant REL as "GitHub Releases"
U->>GH: "Create release / push tag / manually dispatch"
GH->>WF: "Trigger cd workflow"
WF->>GIT: "Checkout repository (fetch-depth 0)"
WF->>CL1: "Run git-cliff v4 with args '-vv --latest --strip header'"
activate CL1
CL1-->>WF: "Output latest changelog snippet (content)"
deactivate CL1
WF->>GIT: "Fetch origin/main and create worktree 'worktree-changelog'"
WF->>CL2: "Run git-cliff v4 in worktree with args '-vv' and env 'OUTPUT=docs/changelog.rst'"
activate CL2
CL2->>GIT: "Write full changelog to 'docs/changelog.rst'"
CL2-->>WF: "Exit with success"
deactivate CL2
WF->>GIT: "Stage changelog changes"
WF->>GIT: "Check if there are staged changes"
alt "Changelog has changes"
WF->>GIT: "Create branch 'changelog/update-<short-hash>'"
WF->>GIT: "Commit with Claude Code signature message"
WF->>GHCLI: "Push branch and create PR to 'main' with labels 'documentation' and 'automated'"
GHCLI->>PRS: "Create PR with changelog updates"
else "No changes"
WF-->>WF: "Skip commit and PR creation"
end
opt "Release or tag-based event"
WF->>GHCLI: "Edit release using tag name and latest snippet"
GHCLI->>REL: "Update release notes with latest changelog content"
end
WF-->>GH: "Workflow completes (worktree cleaned up)"
Flow diagram for branching, commit, and PR creation in changelog workflowflowchart TD
A["Start in worktree-changelog on origin/main"] --> B["Run git-cliff v4 to generate full changelog to 'docs/changelog.rst'"]
B --> C["git add updated changelog files"]
C --> D{"Are there staged changes?"}
D -->|"No"| E["Print 'No changes to commit' and exit step"]
E --> F["Continue to cleanup worktree"]
D -->|"Yes"| G["Create branch 'changelog/update-<short-hash>'"]
G --> H["Commit with message containing Claude Code signature and co-author"]
H --> I["Push branch to origin"]
I --> J["Call 'gh pr create' with base 'main', labels 'documentation' and 'automated'"]
J --> K["PR with changelog updates is opened"]
K --> F["Continue to cleanup worktree"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
🚅 Deployed to the byte-pr-117 environment in byte
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- The multiline commit message constructed with
git commit -m "$(cat <<'EOF' ...)"will include the indentation and may be fragile; consider writing the message to a temporary file and usinggit commit -Fto avoid unintended whitespace and quoting issues. - In the 'Update GitHub release body' step, passing
${{ steps.git-cliff-latest.outputs.content }}directly into--notescan break if the changelog contains quotes or shell-sensitive characters; it would be safer to expose this output as an environment variable or file and reference it from the shell script (e.g.,--notes-file) to avoid quoting/escaping problems.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The multiline commit message constructed with `git commit -m "$(cat <<'EOF' ...)"` will include the indentation and may be fragile; consider writing the message to a temporary file and using `git commit -F` to avoid unintended whitespace and quoting issues.
- In the 'Update GitHub release body' step, passing `${{ steps.git-cliff-latest.outputs.content }}` directly into `--notes` can break if the changelog contains quotes or shell-sensitive characters; it would be safer to expose this output as an environment variable or file and reference it from the shell script (e.g., `--notes-file`) to avoid quoting/escaping problems.
## Individual Comments
### Comment 1
<location> `.github/workflows/cd.yml:62-63` </location>
<code_context>
- git commit -m "docs: update changelog [skip ci]"
- git push origin HEAD:main
+ # Create unique branch name
+ BRANCH_NAME="changelog/update-$(git rev-parse --short HEAD)"
+ git checkout -b "$BRANCH_NAME"
+
+ # Commit with Claude Code signature
</code_context>
<issue_to_address>
**issue:** Using the short commit hash alone for the branch name can cause collisions on reruns.
On re-runs for the same HEAD (manual or retry), this branch name will be the same, causing `git checkout -b` to fail locally and `git push` to fail if the branch already exists on the remote. To avoid this, append something unique like a timestamp or `${{ github.run_id }}` to the branch name, e.g. `changelog/update-$(git rev-parse --short HEAD)-${{ github.run_id }}`.
</issue_to_address>
### Comment 2
<location> `.github/workflows/cd.yml:92-101` </location>
<code_context>
+ env:
+ GH_TOKEN: ${{ github.token }}
+
+ - name: Update GitHub release body
+ if: github.event_name == 'release' || startsWith(github.ref, 'refs/tags/v')
+ run: |
+ # Extract version from tag or release
+ if [ "${{ github.event_name }}" = "release" ]; then
+ TAG_NAME="${{ github.event.release.tag_name }}"
+ else
+ TAG_NAME="${GITHUB_REF#refs/tags/}"
+ fi
+
+ # Update release body with latest changelog
+ gh release edit "$TAG_NAME" \
+ --notes "${{ steps.git-cliff-latest.outputs.content }}" \
+ --repo ${{ github.repository }}
</code_context>
<issue_to_address>
**issue:** Editing releases on tag-based runs may fail when no GitHub Release exists.
This job runs on both `release` events and any `refs/tags/v*` ref. On tag pushes without an existing GitHub Release, `gh release edit "$TAG_NAME"` will fail because the release doesn’t exist. To avoid that, either restrict the `if:` to `github.event_name == 'release'` or add a pre-check (e.g., `gh release view "$TAG_NAME"` and skip if it fails) before editing.
</issue_to_address>
### Comment 3
<location> `.github/workflows/cd.yml:65-66` </location>
<code_context>
+ BRANCH_NAME="changelog/update-$(git rev-parse --short HEAD)"
+ git checkout -b "$BRANCH_NAME"
+
+ # Commit with Claude Code signature
+ git commit -m "$(cat <<'EOF'
+ docs: update changelog
+
</code_context>
<issue_to_address>
**suggestion:** Heredoc indentation will introduce leading spaces in the commit message.
Since the heredoc content is indented to match the YAML, those spaces will appear in the commit subject and body, which may look odd in git log and on GitHub. If that’s not desired, consider left-aligning the heredoc body (no leading spaces on content lines) or using YAML’s `|` block scalar to preserve the intended formatting without extra indentation.
Suggested implementation:
```
BRANCH_NAME="changelog/update-$(git rev-parse --short HEAD)"
git checkout -b "$BRANCH_NAME"
# Commit with Claude Code signature
git commit -m "docs: update changelog"
```
To fully remove the indentation issue from the heredoc, you should also:
1. Delete the remaining lines that belong to this heredoc block (the rest of the commit message body, if any, and the terminating `EOF` line).
2. If you need a multi-line commit message body, either:
- Use a single `-m` with embedded `\n` characters, e.g.:
`git commit -m $'docs: update changelog\n\nAdditional details here.'`
- Or use multiple `-m` flags:
`git commit -m "docs: update changelog" -m "Additional details here."`
Both of these approaches avoid heredoc indentation problems while keeping the YAML nicely indented.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
JacobCoffee
force-pushed
the
feature/optimize-git-cliff-workflow
branch
from
5a98e08 to
b3189f4
Compare
JacobCoffee
force-pushed
the
feature/migrate-to-python3.14
branch
from
f832e7c to
20c8a9c
Compare
Add explicit output file path for git-cliff changelog generation to docs/changelog.rst in pyproject.toml configuration. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Improve CD workflow with: - Upgrade git-cliff-action to v4 for stability - Generate full changelog history (not just latest) - Create PR instead of direct commit to main - Add GitHub release body updates with latest changelog - Use gh CLI for GitHub operations - Add Claude Code signature to commits - Add pull-requests write permission - Use OUTPUT env var instead of --output arg 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Restrict release body update to only release events (not tag pushes) - Fix heredoc indentation using multiple -m flags instead This prevents gh release edit from failing when tags are pushed without an existing GitHub Release.
Append github.run_id to changelog branch name to ensure uniqueness on manual or automatic reruns where the HEAD commit is the same. This prevents git checkout -b and git push failures when the branch already exists from a previous run.
Update sourcery pre-commit hook from v1.40.0 to v1.41.1 to resolve Python 3.13 compatibility issues causing CI failures.
JacobCoffee
force-pushed
the
feature/optimize-git-cliff-workflow
branch
from
ad405f6 to
3e8ecce
Compare
Sourcery v1.41.1 only provides wheels for macOS, causing Linux CI builds to fail. Removing until cross-platform support is available. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
JacobCoffee
commented
Nov 23, 2025
JacobCoffee
commented
Nov 23, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR optimizes the git-cliff changelog workflow in the CD pipeline with several improvements:
Changes
pyproject.toml:
output = "docs/changelog.rst"to git-cliff configcd.yml workflow:
git-cliff-actionfrom@mainto@v4for stability--latestfrom full changelog step)ghCLI for GitHub operationspull-requests: writepermissionOUTPUTenv var instead of--outputin argsWorkflow Behavior
On release/tag/manual trigger:
docs/changelog.rstAtomic commits created:
chore: add output path to git-cliff changelog configci: optimize git-cliff workflow for automated changelogTesting
Note: Full CI cannot run on this branch due to Python 3.14 compatibility issues in base branch (expected, as this is based on
feature/migrate-to-python3.14). Workflow syntax is valid and follows project conventions.🤖 Generated with Claude Code
Summary by Sourcery
Optimize the CD changelog workflow to use the latest git-cliff action, generate both latest and full changelog outputs, and integrate automated PR and release body updates.
New Features:
Enhancements:
CI:
Chores: