Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# The release of the docs and the Claude Code plugin: on a v* tag (pushed
# by Teg, with urbex-cli's of the same version), a GitHub release with the
# version's notes from CHANGELOG.md - the run fails without them
# (urbforge/redemptor#54) - and a link to the CLI's release. A pre-release
# while urbex is 0.x or the tag has a suffix (v0.1.0-rc.1).
name: release

on:
push:
tags: ["v*"]

permissions:
contents: read

concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false

jobs:
release:
if: github.repository == 'urbforge/urbex'
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write # the release
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Publish the release with its notes
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ github.ref_name }}
run: |
version=${TAG#v}
plugin=$(sed -n 's/^ *"version": "\(.*\)",$/\1/p' .claude-plugin/plugin.json)
notes=$RUNNER_TEMP/notes.md
{
echo "The docs and the Claude Code plugin ($plugin) of urbex $version."
echo "The CLI, \`urbex-op\` and its image: [urbforge/urbex-cli $TAG](https://github.com/urbforge/urbex-cli/releases/tag/$TAG)."
echo
# The changelog's links are relative to the repository; on the
# release's page they point to this tag's files.
scripts/release-notes.sh "$TAG" | sed "s#](docs/#](https://github.com/$GITHUB_REPOSITORY/blob/$TAG/docs/#g; s#](CHANGELOG.md#](https://github.com/$GITHUB_REPOSITORY/blob/$TAG/CHANGELOG.md#g"
} >"$notes"
case "$TAG" in
v0.* | *-*) pre=--prerelease ;;
*) pre= ;;
esac
gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag \
--title "urbex $version - docs and plugin $plugin" --notes-file "$notes" $pre
57 changes: 57 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Changelog

What changed in each release of urbforge/urbex: the documentation and
the **Claude Code plugin** (`.claude-plugin`, `skills/`). The format
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), with
**Breaking** and **Upgrading** sections when a release needs them.

urbex is tagged together with urbex-cli (`v0.1.0` in both); the CLI, the
`urbex-op` script and its image have their own changelog, in
[urbforge/urbex-cli](https://github.com/urbforge/urbex-cli/blob/main/CHANGELOG.md).

**The plugin has its own version**, in `.claude-plugin/plugin.json`. It
works with any `urbex` of the same major version; while both are 0.x a
minor may still break, so each plugin version states the minimum `urbex`
it needs (see [Upgrading](docs/upgrading.md#plugin-and-cli-versions)).

A pull request that changes what users see adds a line under
*Unreleased*; a release moves them under its version - the release
workflow refuses a tag whose version has no entry here.

## [Unreleased]

## [0.1.0] - 2026-11-17

The first preview release: the docs install urbex from the
[urbex-cli v0.1.0 release](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0)
instead of a clone.

### Plugin 0.2.0

Needs **urbex 0.1.0 or later, major 0**.

- **Added**: the plugin's own version, and its check of `urbex version`
once per session: it says when urbex is older than it needs, or of
another major.
- **Changed**: the `setup` skill downloads `urbex-op` from the newest
release instead of cloning and building urbex-cli; its prerequisites
check reads the image from `urbex-op version`.
- The `setup`, `cli` and `manifest` skills: setting up the platform from
an empty Proxmox node, every `urbex` command with the ones that need
your confirmation, and writing `urbex.yaml`.

### Docs

- **Added**: [Upgrading](docs/upgrading.md); `urbex version` in the CLI
reference.
- **Changed**: getting started (with the CLI, Claude Code or another
agent) and the cookbook install from the release; the README says
*preview release* and links the known limitations.

### Known limitations

A preview: no backups of the platform yet, Proxmox only, a single
operator. See the [known limitations](docs/known-limitations.md).

[Unreleased]: https://github.com/urbforge/urbex/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/urbforge/urbex/releases/tag/v0.1.0
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,9 @@ Start here:
[CLI](docs/getting-started/with-the-cli.md), [any AI
agent](docs/getting-started/with-an-ai-agent.md) or [Claude
Code](docs/getting-started/with-claude-code.md).
- [**Upgrading**](docs/upgrading.md) — moving to a new release.
- [**Upgrading**](docs/upgrading.md) — moving to a new release; what
changed in each: [`CHANGELOG.md`](CHANGELOG.md) (docs and plugin) and
urbex-cli's [`CHANGELOG.md`](https://github.com/urbforge/urbex-cli/blob/main/CHANGELOG.md).
- [**Cookbook**](docs/cookbook.md) — recipes: releasing, rolling back,
pinning staging, secrets, adding services, troubleshooting, driving
Urbex from an LLM agent (the Claude Code plugin included).
Expand Down
6 changes: 4 additions & 2 deletions docs/upgrading.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ the tools on your machine. The workspace, the GitOps repo, the platform
and your projects stay as they are.

While Urbex is 0.x (a preview), a minor release may still change how
something works. **Read the release's notes first**: they say when a
command is needed after upgrading.
something works. **Read the release's notes first** - its GitHub release,
or the `CHANGELOG.md` of [urbex-cli](https://github.com/urbforge/urbex-cli/blob/main/CHANGELOG.md)
and of [this repository](../CHANGELOG.md): their *Breaking* and
*Upgrading* sections say when a command is needed after upgrading.

## With urbex-op

Expand Down
21 changes: 21 additions & 0 deletions scripts/release-notes.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
#!/bin/bash
# release-notes.sh TAG [CHANGELOG]: the release notes of TAG (v0.2.0, v0.2.0-rc.1)
# from CHANGELOG.md - the section "## [0.2.0] ..." without its heading -
# for the GitHub release. An -rc takes the notes of its version. Fails,
# saying so, when the version has no section or an empty one: a release
# needs its notes (urbforge/redemptor#54).
set -euo pipefail
tag=${1:?usage: release-notes.sh TAG [CHANGELOG]}
file=${2:-CHANGELOG.md}
version=${tag#v}
version=${version%%-*}
notes=$(awk -v v="$version" '
/^## \[/ { if (on) exit; on = (index($0, "## [" v "]") == 1); next }
/^\[[^]]+\]: / { next }
on { print }
' "$file" | sed -e '/./,$!d' | sed -e ':a' -e '/^\n*$/{$d;N;ba' -e '}')
if [ -z "$notes" ]; then
echo "release-notes.sh: $file has no notes for $version: add a '## [$version] - <date>' section (move the Unreleased lines there)" >&2
exit 1
fi
printf '%s\n' "$notes"
12 changes: 12 additions & 0 deletions tests/plugin-scripts.sh
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,15 @@ for arg, want in [
print("ok prepare-proxmox.py parse_host")
sys.exit(1 if failed else 0)
PY
py_rc=$?

# The plugin's version has its notes in CHANGELOG.md ("### Plugin X",
# under its release or Unreleased) - urbforge/redemptor#54.
plugin=$(sed -n 's/^ *"version": "\(.*\)",$/\1/p' .claude-plugin/plugin.json)
if grep -q "^### Plugin $plugin\$" CHANGELOG.md; then
echo "ok CHANGELOG.md has plugin $plugin"
else
echo "FAIL CHANGELOG.md has no '### Plugin $plugin' section: add the plugin's notes" >&2
exit 1
fi
exit "$py_rc"