Release notes are malformed

[jasonkarns]

The diff/changelog links in release notes for this action are broken/malformed.

See latest release: https://github.com/step-security/harden-runner/releases/tag/v2.13.0

Full changelog link is v2...v2.13.0

Note how the changelog is diff-ing 2.13.0 with v2 and not with 2.12.2.

This is because the action is using v2 "major version" tag. That "major version" git ref should be a branch, not a tag because the ref is continually updated each release. (Git conventions expect tags to be generally immutable. Branches are mutable.)

[varunsh-coder]

Thanks @jasonkarns for reporting this.
I looked at https://github.com/actions/checkout/releases/tag/v4.2.2 and it uses a diff with the previous version.
We will plan to do the same going forward - diff with the previous version.

I will check if we can update release notes for the current release.

[jasonkarns]

I looked at https://github.com/actions/checkout/releases/tag/v4.2.2 and it uses a diff with the previous version.

Did you intend to link to the actions/checkout release for that example? I'm not sure what that has to do with step-security/harden-runner releases.

To clarify: this is a known issue with GitHub's automatic release notes. It is caused by the presence of the v2 tag that github sees as the "most recent ancestor tag" at the moment the release is generated.

One solution to the problem is to not use github's automated release notes. (But realistically, that's not a great solution because why should action authors needs to build our own custom changelog generator just because GitHub's is buggy?)

The alternative is to stop using v2 "major version" tags and use branches instead. Without the "major version" tags (like v1, v2, v3, etc), then github's release notes API will more accurately generate correct diff URLs. (Because without v2 tag, the next most recent tag would have correctly been detected as v2.12.2.)

GitHub Actions doesn't treat tag refs any differently than branch refs, so you can just as easily use v1, v2, v3 "major version" branches instead of tags. The side benefit of using branches for those major-version refs (necessary to accommodate github actions' lack of versioning) is that you're no longer violating git conventions (tags being immutable, that is). Additionally, you don't have to worry about your own GHA workflows being triggered by vN* tag-push events.

[varunsh-coder]

Sorry, I should have clarified. The reason I linked to https://github.com/actions/checkout/releases/tag/v4.2.2 was to look at how other action authors are solving this problem.

I am hesitant to create a v2 branch since we already have a v2 tag and it might cause confusion.

Moreover, we do not use GitHub's automated release notes.

Given these points, we plan to have a diff to the previous version and not v2 for future release notes.

[jasonkarns]

Sorry, I should have clarified. The reason I linked to https://github.com/actions/checkout/releases/tag/v4.2.2 was to look at how other action authors are solving this problem.

Ah, gotcha. I've encountered other actions that are bitten by the same GH Release "bug". The simplest (but not cleanest, IMO) fix is to explicitly tell github the prior release. (either via the UI or the gh cli) Then the generated notes are accurate.

I am hesitant to create a v2 branch since we already have a v2 tag and it might cause confusion.

Understood. Though you can always delete the tag so there only exists a single unambiguous ref. (Which is effectively what is happening now. Each time the action is released, the tag is force-pushed. Which is the same as a delete + new tag.)

Moreover, we do not use GitHub's automated release notes.

My mistake. I made that assumption because the release notes look the same as what github generates. I also found https://github.com/step-security/reusable-workflows/blob/main/.github/workflows/actions_release.yaml#L290-L293 which is using the generated notes. Perhaps that workflow isn't actually being used?

Given these points, we plan to have a diff to the previous version and not v2 for future release notes.

🎉