enh(CI): Automatic Release Workflow

[marmitar]

Automatic Release Workflow

This PR introduces a release workflow that runs on the first day of every month, checks for changes on master and, if so, creates a new release after approval.

• Closes New release #57

Tag Selection

The verify job selects a tag name with format %Y.%m.%d (e.g. 2025.08.01), which always ends in 01 since it runs on the first day of each month. If the tag is newer than the previous one and there are changes in master, then the workflow generates a change summary and continues to the release job, which requests a review and awaits for approval.

The examples below use format %Y.%m.%d-%H for faster (test) release cycles, but everything else is the same.

Summary

The summary is generated with git diff --histogram --stat $latest_tag..$release_commit and git log --no-merges $latest_tag..$release_commit, so merge commits are not displayed.

To prevent new commits from being integrated into the release without showing up on the summary, the verify job also provides the release_commit used.

Release Summary

## Proposing new release `2025.07.14-05`
### Changes since [`2025.07.13-23`](https://github.com/marmitar/nano-syntax-highlighting/releases/tag/2025.07.13-23)
```log
 git.nanorc | 17 ++++++++---------
 readme.md  |  7 +++----
 2 files changed, 11 insertions(+), 13 deletions(-)
```
### Git log
```log
commit ce788aa4e727ea09e542c8b91e59574645dc75a0
Author: Tiago de Paula <tiagodepalves@gmail.com>
Date:   Sun Jul 13 23:32:45 2025 -0300

    enh(gitcommit): improve colors for kitty+fish combo

commit 22592a37ddc9639b206f4c6e5859d4421348b4dd
Author: Tiago de Paula <tiagodepalves@gmail.com>
Date:   Sun Jul 13 23:24:01 2025 -0300

    chore(readme): add release badge

commit dd9e3ca50d430f6ffc1b8c4d79af76e37b52f754
Author: Tiago de Paula <tiagodepalves@gmail.com>
Date:   Sun Jul 13 23:17:13 2025 -0300

    chore(readme): restore package manager information
```

---

• Examples: #30, #35, #37

Checks

Each tag is checked to be newer using lexicographical order, which works for %Y.%m.%d. Just be aware of any additional text after the date. For example, 2025.07.01-2 is considered newer than 2025.07.01-10.

After that, the last commit on master is compared to the $latest_tag, and the release is skipped if no change is reported.

In both cases, skipping the relase is not considered a failure. The workflow just finishes early and no notification is sent anywhere.

Outdated Release

## Skipping release `2025.07.13-23`
Latest tag [`2025.07.13-23`](https://github.com/marmitar/nano-syntax-highlighting/releases/tag/2025.07.13-23) already covers this date.

---

Release with No Changes

## Skipping release `2025.07.14-02`
No changes since [`2025.07.13-23`](https://github.com/marmitar/nano-syntax-highlighting/releases/tag/2025.07.13-23).

---

• Examples: #31, #32, #33, #36

Manual Release

The job can also be triggered manually on Actions page, with an optional release_tag different from %Y.%m.%d. You can also change the deploy environment for this manual run.

Full Page

Workflow Review

Once verify completes with a non-empty release_tag, the workflow request reviews from defined members before starting the release job.

The release job pins the release to exact $release_commit provided by verify, independently of how long the review process take. Once a release is verified, its commit is fixed. To include newer commits you must cancel and rerun the workflow.

Release Verified, Awaiting Review

Review Notification Sent to Email

Review Page

Release Approved

Release Created

GitHub Environment

Important

This step requires manual configuration in the repository Settings.

The review system uses deploy environments on Github. The workflow doesn't actually use any information from the environment, but if the environment is configured with "Required reviewers", then it won't run by itself. Here I used release as the name of the environment.

Environment Settings

Job Concurrency

To avoid multiple competing releases, I've set up a concurrency group that disallows concurrent runs of the release.yml workflow. If a new workflow starts while the last one is still running, then the new one has priority and the other is cancelled. In practice, this should only happen if a release is left unapproved for more than a month.

Unapproved Release

• Example: #24, #25, #26, #27, #28, #29

Release Creation

Once the release job is approved and runs, it creates a tag with the name $release_tag provided by verify, pointing to the pinned $release_commit. It also creates a GitHub release with automatically generated release notes, which can be configured in a .github/release.yml file. By default, the generated notes list all pull requests since the last release (which might be a lot for the first one here, you can create a first release to avoid this).

Changelog Example

• Examples: 2025.07.13-23, 2025.07.14-05, 2025.07.14-07

Implementation Notes

There's currently an issue (actions/checkout#1467) with fetch_tags on Git 2.48 (ubunut-latest), which requires explicit fetching of the git history using fetch-depth and ref. I used the last 100 commits for fetch-depth, which should be more than enough for a month. The workaround implemented here can be removed after the fix actions/checkout#2200 lands.

[marmitar]

@davidhcefx @galenguyer Sorry for the lengthy description. Hope it serves as some kind of documentation for anyone needing to change it in the future.

[marmitar]

I've added a release_commit output that pins the exact same SHA across jobs, so no change is inserted without proper review. I've updated the PR description to reflect this, but not the images. Here's how the summary looks like with the pinned commit:

Release Summary

## Proposing new release `2025.07.14-08`
Commit: [5664935f4551e95f140f5670d7152202eb7b41c2](https://github.com/marmitar/nano-syntax-highlighting/commit/5664935f4551e95f140f5670d7152202eb7b41c2)
### Changes since [`2025.07.14-07`](https://github.com/marmitar/nano-syntax-highlighting/releases/tag/2025.07.14-07)
```log
 .github/workflows/release.yml | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
```
### Git log
```log
commit 5664935f4551e95f140f5670d7152202eb7b41c2
Author: Tiago de Paula <tiagodepalves@gmail.com>
Date:   Mon Jul 14 04:42:05 2025 -0300

    fix(ci): pin commit
```

Edit: sorry, I was editing the PR text in VSCode and included it in the code by mistake.

[marmitar]

Just got a review request for a release in my test fork, so it seems to be working correctly.

[marmitar]

Updated to actions/checkout@v5.