Welcome Releasepost
Posted May 23, 2024 by olblak ‐ 10 min read
No matter the project I am working on, I am constantly looking for project release notes.
The good news is we now have access to great tools to automatically generate those release notes such as Release Drafter, Changie, Conventional Changelog, etc.
In 2024, there is no excuse to skip that critical piece of information.
The sad news is that I now spend a significant amount of time searching for those release notes on platforms like GitHub…
What if I could visualize Updatecli changelogs from www.updatecli.io?
How many people read release notes?
Does it even make sense to spend effort maintaining those release notes?
To try to answer those questions, I made a small experiment:
Reposting automatically Updatecli release notes to updatecli.io, in a way that would allow me to reuse this pipeline for others projects.
Considering updatecli.io is powered by HUGO, all I need is a way to automate the synchronization of GitHub release pages with my website’s Git repository.
Updatecli already works great to automatically push file updates to git repositories.
Welcome Releasepost.
Releasepost
Releasepost can be downloaded from github.com/updatecli/releasepost.
It is an experimental command line tool that fetches information from a remote location like GitHub releases and then generates files locally such as:
.
├── changelogs
│ ├── v0.9.0.md
│ ├── v0.9.1.md
│ ├── v0.9.2.md
│ ├── v0.9.3.md
│ └── v0.9.4.md
└── index.md
Where the directory changelogs contains one file per changelog, and index.md a list of links to the various changelogs file.
In theory, it’s as simple as that…
Let’s see the Releasepost configuration used to generate www.updatecli.io./changelogs:
releasepost.yaml
changelogs:
- kind: github
dir: content/en/changelogs/updatecli
formats:
- extension: asciidoc
frontmatters: |
---
title: "{{ .Changelog.Name }}"
date: {{ .Changelog.PublishedAt }}
---
indexfilename: _index
indexfrontmatters: |
---
title: "Changelogs"
---
- extension: json
indexfilename: _index
spec:
owner: updatecli
repository: updatecli
sourced from releasepost.yaml
The most important settings are:
spec.ownerandspec.repositoryspecify the GitHub repository to monitor for release notes.dirspecifies where to generate the files.formatsspecifies the kind of files we want to generate so in this case json and Asciidoctor.
This configuration relies on the environment variable RELEASEPOST_GITHUB_TOKEN to set the GitHub credentials used to interact with the API.
HUGO relies on specific behaviors like front-matters to provide page metadata or an index file name that differs from other tools like Docusaurus.
I must admit, I envisioned a simpler configuration that would only contain the GitHub repository to monitor, but as always, the Devil hides in the details.
NOTE: More customization is available such as version filtering or the credentials to use but let’s keep that for later.
You can try releasepost by running:
export RELEASEPOST_GITHUB_TOKEN=<insert here a GitHub personal token>
releasepost --config releasepost.yaml
Updatecli
Running releasepost --config creates the files locally but it’s only halfway.
We want to automatically publish them to our git repository.
The next step was to write an Updatecli policy that would run releasepost and take care of opening pull requests when needed, such as updatecli/website#1428.
Updatecli Policy
On the Updatecli project, we are using this Update policy:
-> ghcr.io/updatecli/policies/releasepost/releasepost:0.1.0
To visualize the pipeline of this policy:
Without SCM configured
$ updatecli manifest show ghcr.io/updatecli/policies/releasepost/releasepost:0.1.0
+++++++++++
+ PREPARE +
+++++++++++
Loading Pipeline "/tmp/updatecli/store/6a8e68ae473a5dafa270650cd74fd296e61abaf4820daf4b50e0e21c8649b710/updatecli.d/default.tpl"
SCM repository retrieved: 0
++++++++++++++++++
+ AUTO DISCOVERY +
++++++++++++++++++
++++++++++++++++++++++++++++++++++
+ DOCS: SYNCHRONIZE RELEASE NOTE +
++++++++++++++++++++++++++++++++++
name: 'docs: synchronize release note'
pipelineid: releasepost
targets:
default:
name: synchronize release notes
kind: shell
spec:
changedif:
kind: exitcode
spec:
failure: 2
success: 1
warning: 0
command: releasepost --dry-run="$DRY_RUN" --config .releasepost.yaml
environments:
- name: GITHUB_TOKEN
- name: RELEASEPOST_GITHUB_TOKEN
- name: PATH
version: 0.77.0
With SCM configured
updatecli/values.d/scm.yaml
scm:
enabled: true
user: updatecli-bot
email: updatecli-bot@updatecli.io
owner: updatecli
repository: website
username: "updatecli-bot"
branch: master
sourced from github.com/updatecli/website/updatecli/values.d/scm.yaml
updatecli manifest show --values updatecli/values.d/scm.yaml ghcr.io/updatecli/policies/releasepost/releasepost:0.1.0
+++++++++++
+ PREPARE +
+++++++++++
Loading Pipeline "/tmp/updatecli/store/6a8e68ae473a5dafa270650cd74fd296e61abaf4820daf4b50e0e21c8649b710/updatecli.d/default.tpl"
SCM repository retrieved: 1
++++++++++++++++++
+ AUTO DISCOVERY +
++++++++++++++++++
++++++++++++++++++++++++++++++++++
+ DOCS: SYNCHRONIZE RELEASE NOTE +
++++++++++++++++++++++++++++++++++
name: 'docs: synchronize release note'
pipelineid: releasepost
actions:
default:
kind: github/pullrequest
spec:
automerge: false
labels:
- documentation
scmid: default
scms:
default:
kind: github
spec:
branch: master
email: updatecli-bot@updatecli.io
owner: updatecli
repository: website
token: ghp_xxx
user: updatecli-bot
username: updatecli-bot
disabled: false
targets:
default:
name: synchronize release notes
kind: shell
spec:
changedif:
kind: exitcode
spec:
failure: 2
success: 1
warning: 0
command: releasepost --dry-run="$DRY_RUN" --config .releasepost.yaml
environments:
- name: GITHUB_TOKEN
- name: RELEASEPOST_GITHUB_TOKEN
- name: PATH
scmid: default
version: 0.77.0
To visualize what this pipeline would change
updatecli diff ghcr.io/updatecli/policies/releasepost/releasepost:0.1.0
Please note that to make the following output smaller, the Releasepost configuration was modified to monitor the GitHub repository updatecli/udash which contains far less releases than updatecli/updatecli
+++++++++++
+ PREPARE +
+++++++++++
Loading Pipeline "/tmp/updatecli/store/6a8e68ae473a5dafa270650cd74fd296e61abaf4820daf4b50e0e21c8649b710/updatecli.d/default.tpl"
SCM repository retrieved: 0
++++++++++++++++++
+ AUTO DISCOVERY +
++++++++++++++++++
++++++++++++
+ PIPELINE +
++++++++++++
##################################
# DOCS: SYNCHRONIZE RELEASE NOTE #
##################################
TARGETS
========
default
-------
**Dry Run enabled**
The shell 🐚 command "/bin/sh /tmp/updatecli/bin/be57548ac59ed9a80520b8dd8275573480aa383875ea4597afc606297a890735.sh" ran successfully with the following output:
----
Running releasepost
Dry run mode enabled, no changelog will be saved to disk
Searching releases
GitHub Api credit used 1, remaining 4141 (reset at 2024-05-21T14:08:48Z)6 releases foundRelease found: v0.4.1
Looking for release information related to version v0.4.1 from updatecli/udash
Looking for release assets related to version v0.4.1 from updatecli/udash
GitHub Api credit used 1, remaining 4139 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4138 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4137 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4136 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4135 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4134 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4133 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4132 (reset at 2024-05-21T14:08:48Z) => found 15 assets
Release found: v0.4.0
Looking for release information related to version v0.4.0 from updatecli/udash
Looking for release assets related to version v0.4.0 from updatecli/udash
GitHub Api credit used 1, remaining 4130 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4129 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4128 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4127 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4126 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4125 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4124 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4123 (reset at 2024-05-21T14:08:48Z) => found 15 assets
Release found: v0.3.0
Looking for release information related to version v0.3.0 from updatecli/udash
Looking for release assets related to version v0.3.0 from updatecli/udash
GitHub Api credit used 1, remaining 4121 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4120 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4119 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4118 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4117 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4116 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4115 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4114 (reset at 2024-05-21T14:08:48Z) => found 15 assets
Release found: v0.2.0
Looking for release information related to version v0.2.0 from updatecli/udash
Looking for release assets related to version v0.2.0 from updatecli/udash
GitHub Api credit used 1, remaining 4112 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4111 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4110 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4109 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4108 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4107 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4106 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4105 (reset at 2024-05-21T14:08:48Z) => found 15 assets
Release found: v0.1.1
Looking for release information related to version v0.1.1 from updatecli/udash
Looking for release assets related to version v0.1.1 from updatecli/udash
GitHub Api credit used 1, remaining 4103 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4102 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4101 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4100 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4099 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4098 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4097 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4096 (reset at 2024-05-21T14:08:48Z) => found 15 assets
Release found: v0.1.0
Looking for release information related to version v0.1.0 from updatecli/udash
Looking for release assets related to version v0.1.0 from updatecli/udash
GitHub Api credit used 1, remaining 4094 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4093 (reset at 2024-05-21T14:08:48Z)GitHub Api credit used 1, remaining 4092 (reset at 2024-05-21T14:08:48Z) => found 6 assets
Generating changelogs
Generating index
Cleaning
Untracked files detected:
* content/en/changelogs/updatecli/changelogs/v0.0.1.adoc
Result
* content/en/changelogs/updatecli/changelogs/v0.4.1.adoc (created)
* content/en/changelogs/updatecli/changelogs/v0.4.1.json (created)
* content/en/changelogs/updatecli/changelogs/v0.4.0.adoc (modified)
* content/en/changelogs/updatecli/changelogs/v0.4.0.json (modified)
* content/en/changelogs/updatecli/changelogs/v0.3.0.adoc (modified)
* content/en/changelogs/updatecli/changelogs/v0.3.0.json (modified)
* content/en/changelogs/updatecli/changelogs/v0.2.0.adoc (modified)
* content/en/changelogs/updatecli/changelogs/v0.2.0.json (modified)
* content/en/changelogs/updatecli/changelogs/v0.1.1.adoc (modified)
* content/en/changelogs/updatecli/changelogs/v0.1.1.json (modified)
* content/en/changelogs/updatecli/changelogs/v0.1.0.adoc (modified)
* content/en/changelogs/updatecli/changelogs/v0.1.0.json (modified)
* content/en/changelogs/updatecli/_index.adoc (modified)
* content/en/changelogs/updatecli/_index.json (modified)
----
⚠ - ran shell command "releasepost --dry-run=\"$DRY_RUN\" --config .releasepost.yaml"
ACTIONS
========
=============================
REPORTS:
⚠ docs: synchronize release note:
Target:
⚠ [default] synchronize release notes
Run Summary
===========
Pipeline(s) run:
* Changed: 1
* Failed: 0
* Skipped: 0
* Succeeded: 0
* Total: 1
That policy source is available on github.com/updatecli/policies
Well, we are almost there, I have an Updatecli policy working locally but I am not ready yet to ship my laptop to the cloud for running Updatecli command.
Let’s run Updatecli from the cloud.
Automation
Here we are in the final stage where we see how we leverage a CI tool to periodically run updatecli which then runs releasepost.
First we need to specify the list of Updatecli policies to execute periodically. In this example, we only have one policy for running releasepost.
updatecli-compose.yaml
policies:
- name: Trigger releasepost
policy: ghcr.io/updatecli/policies/releasepost/releasepost:0.1.0
values:
- updatecli/values.d/scm.yaml
sourced from github.com/updatecli/website/update-compose.weekly.yaml
It’s worth highlighting that Updatecli policies can be customized using values files. In this case we want to update the branch “master” on the GitHub repository “updatecli/website”
updatecli/values.d/scm.yaml
scm:
enabled: true
user: updatecli-bot
email: updatecli-bot@updatecli.io
owner: updatecli
repository: website
username: "updatecli-bot"
branch: master
sourced from updatecli/values.d/scm.yaml
Finally we configure our GitHub Action workflow.
.github/workflows/updatecli.yaml
---
name: Updatecli
on:
workflow_dispatch:
schedule:
# * is a special character in YAML so you have to quote this string
# Run at 12:00 every Thursday
- cron: '0 12 * * 4'
jobs:
updatecli:
if: github.ref == 'refs/heads/master'
runs-on: ubuntu-latest
steps:
- name: "Checkout"
uses: "actions/checkout@v4"
- name: "Install Updatecli"
uses: "updatecli/updatecli-action@v2"
# releasepost is required by the Updatecli
# * policy ghcr.io/updatecli/policies/releasepost/releasepost
- name: "Install Releasepost"
uses: "updatecli/releasepost-action@main"
- name: "Run updatecli"
run: "updatecli compose apply --file update-compose.weekly.yaml"
env:
GITHUB_ACTOR: ${{ github.actor }}
## Used by Updatecli to interact with GitHub api
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
## Used by Releasepost to interact with GitHub api
RELEASEPOST_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
sourced from github.com/updatecli/website/.github/workflows/updatecli.weekly.yaml
Conclusion
Here we are, to automate release note publishing to a documentation website.
We need three files:
- A releasepost configuration that specifies the GitHub repository to monitor.
- An updatecli-compose.yaml file listing Updatecli policies to enforce.
- A values file listing the GitHub repository to monitor for release notes and the GitHub repository to copy those release notes.
- A GitHub action workflow to execute Updatecli periodically.
To answer my initial questions.
What if I could visualize Updatecli changelogs from www.updatecli.io?
It’s been working great for a few months now, and I am not looking back.
How many people read release notes?
Traffic show me that people/crawler do care.
Does it even make sense to spend effort maintaining those release notes?
I do think so, manually crafted release notes are by far the best ones but they are also the most time-consuming. It’s difficult to maintain them over time for every project so automatically generated release notes are a good alternative.
I wish more projects consider release notes as a critical component of their releases.
Next steps
This project was built with flexibility in mind, so we could definitely envision building plugins for NPM, Gitlab releases, etc.
In the near future, I am considering documenting how we automate release notes publishing on Docusaurus website by leveraging the versioning feature. In that scenario, we only need release notes associated to the versioned website.
Example on fleet.rancher.io/0.9/changelogs
All of this doesn’t replace the need to write good release notes, we just try to make them more visible.
Feedback
Feel free to reach out on our chat to share feedback.
As a sign of appreciation, you can star one of our GitHub repositories.