3.7 KiB
Release workflow
This document covers the automatic creation of release binaries of MD-CMS for Linux, macOS and Windows. This document is relevant for you who want to continue developing MD-CMS on your own.
Prerequisites
- Push access to your GitHub release repository
- GitHub Actions enabled on the repository (it is by default on new repos)
One-time GitHub setup
Enable workflow write permissions
The release workflow creates a GitHub release using the built-in GITHUB_TOKEN. You need to confirm it has write access:
- Go to your repository on GitHub
- Go to Settings → Actions → General
- Scroll to Workflow permissions
- Select Read and write permissions
- Click Save
That's the only setup required. No secrets, no tokens, no third-party services.
The release checklist
Update version number
Before tagging a release, update the version number in at least places:
mdcms.py — find this line near the top and bump it:
CLI_VERSION = "0.3.8"
pyproject.toml — bump the matching line:
version = "0.3.8"
If you have made changes that affect the index.html and/or config.yml, update the minimum supported version comment at the top of each file:
app/index.html — bump the matching line:
<!-- Minimum supported version: mdcms v0.3.8 | DO NOT REMOVE THIS COMMENT -->
app/config.yml — bump the matching line:
# Minimum supported version: mdcms v0.3.2 | DO NOT REMOVE THIS COMMENT
Commit locally
Commit the version bump:
git add mdcms.py pyproject.toml
git commit -m "Bump version to 0.3.8"
git push origin main
Commit on the web
Save each file with a version bump notice: "Bump version to 0.3.8".
Tagging the release
Locally
Push a version tag to trigger the workflow:
git tag v0.3.8
git push origin v0.3.8
On the web
- Go to your repository → Releases (right sidebar)
- Click Draft a new release
- Click Choose a tag → type v0.3.7 → click Create new tag: v0.3.8 on publish
- Leave the target branch as main
- Click Generate release notes
- Click Publish release
The binaries will be generated by
Common
The tag must start with v. The workflow triggers immediately.
Pre-releases — if the tag contains a hyphen (e.g.
v0.4.0-beta.1), the GitHub release is automatically marked as pre-release.
What the workflow does
The workflow (.github/workflows/release.yml) runs three parallel jobs:
| Runner | Output |
|---|---|
ubuntu-latest |
mdcms-linux-amd64 (standalone binary) + mdcms_0.3.1_amd64.deb |
macos-latest |
mdcms-macos-arm64 (standalone binary) |
windows-latest |
mdcms-windows-amd64.exe |
Each binary is built with PyInstaller — Python is bundled inside, so end users need nothing pre-installed. The .deb is built with fpm and installs mdcms to /usr/local/bin.
A final job collects all artifacts and creates the GitHub release with auto-generated release notes.
Monitoring the build
- Go to Actions on the repository
- Click the workflow run triggered by your tag
- Each platform job takes roughly 3–5 minutes
If a job fails, the release is not created. Fix the issue, delete the tag, and re-push:
git tag -d v0.3.8
git push origin --delete v0.3.8
Fix the issue, then re-tag:
git tag v0.3.8
git push origin v0.3.8
The finished release
Once all jobs pass, the release appears under Releases on the repository with:
- Auto-generated changelog (commits since the last tag)
- All four artifacts attached for download
Follow-up
If you serve latest binaries from a standard URL, you also have to make sure to update these.