What the agent does
The agent reads how the plugin is built and how releases are made today. In a plugin laid out like blacksmithgu/obsidian-dataview, package.json builds with npx rollup --config rollup.config.js --environment BUILD:production, which rollup.config.js turns into two outputs: the plugin bundle at build/main.js and a library build under lib/ for the npm package. manifest.json carries version 0.5.68 while package.json and manifest-beta.json say 0.5.70, and versions.json maps each plugin version to the minAppVersion it needs, 0.13.11 for the latest two. CI in .github/workflows/test.yml runs three jobs on Node 16 with npm install, one each for npm run check-format, npm run build and npm run test, and documentation.yml deploys the MkDocs site whenever a release is published.
Releases are a shell script. scripts/release needs jq, gh and an EDITOR, prepends release notes to CHANGELOG.md and copies it to docs/docs/changelog.md, rewrites the version in package.json, manifest.json, manifest-beta.json and versions.json, commits as Auto-release <version>, pushes, builds, runs npm publish, and finally gh release create with build/main.js, styles.css and manifest.json as assets. scripts/beta-release does the same with --pre-release and touches only the beta manifest. Every step runs on one maintainer's machine, so a release depends on that machine's Node, its npm login and its gh session.
The agent adds .github/workflows/release.yml, triggered by a pushed tag of the form x.y.z. The job checks out the tag, sets up the same Node 16 that test.yml uses, installs with npm ci so the lockfile is honoured, runs npm run build, and then checks that the tag equals version in manifest.json and that versions.json has an entry for it, failing with a clear message when the files were not bumped. It creates the GitHub release as a draft with gh release create --draft --verify-tag, attaching build/main.js, manifest.json and styles.css under exactly those names, since Obsidian's community plugin installer downloads them by name, and using the top section of CHANGELOG.md as the notes. A tag that manifest-beta.json matches but manifest.json does not is marked a prerelease. Publishing the draft is a person's click, and that click is what already triggers documentation.yml.
The npm publish stays out of the workflow unless the repository has an NPM_TOKEN secret; the pull request explains how to add one and the single step that would use it. The agent trims scripts/release to the version bump and the commit, leaving the build and the release to the workflow, and runs npm ci, npm run build and actionlint in its sandbox before opening the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a GitHub release workflow to this Obsidian plugin. Read package.json, rollup.config.js, manifest.json, manifest-beta.json, versions.json, scripts/release, scripts/beta-release and every file under .github/workflows first. Write .github/workflows/release.yml triggered by an x.y.z tag push: check out the tag, use the Node version the existing CI uses, npm ci, run the production build, fail unless the tag matches the version in manifest.json and has an entry in versions.json, and create a draft release with gh release create --verify-tag that attaches main.js, manifest.json and styles.css under those exact names, with the top CHANGELOG.md section as notes; mark the release a prerelease when only manifest-beta.json matches the tag. Give the job contents: write and nothing more. Leave npm publish out unless an NPM_TOKEN secret exists, and reduce scripts/release to the version bump and commit. Run npm ci, the build and actionlint in the sandbox, then open a pull request that explains the new release steps for a maintainer.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds .github/workflows/release.yml, shortens scripts/release and scripts/beta-release to the version bump and the commit, and adds a short release section to README.md or CONTRIBUTING.md describing the tag-and-publish flow. Its description lists the workflow's permissions, the asset names it uploads, the checks it makes against manifest.json and versions.json, and the actionlint result.
After the merge, a release is a version bump commit and a pushed tag; the draft appears with its three assets and the maintainer publishes it from the GitHub UI, which also deploys the documentation as before.
Before merging, a reviewer confirms the Node version matches test.yml, decides whether the draft step is wanted or whether the release should publish straight away, and checks that build/main.js is uploaded as main.js, the name the plugin installer expects.
Run it on every release tag
A developer who maintains several plugins sends this body once per repository from a script, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own build: a plugin bundled with esbuild gets a workflow that runs that build, and one with no versions.json check in its scripts gets the check added.
Once the workflow exists, a handler on the maintainer's server receives GitHub's release webhook for the repository and, on a published release, sends POST /o/{org}/sessions with this repository in resources, the release URL and "read this release's assets and notes and report anything missing against the plugin's manifest" as input, and a request_id that is a UUID v5 of the delivery id, so a redelivery starts no second run. GitHub signs its webhooks and cannot send a custom Authorization header, so it cannot call a Rush webhook trigger directly, and no github trigger fires on a release. The result comes back on the session or through the key's webhook_url, and the run pushes nothing.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A release script that lives on one machine fails in ways nobody else can reproduce: a different Node, an expired npm login, a gh that is not signed in. The agent moves the build and the release into a workflow and checks each step in its own sandbox, with the build log and the actionlint output kept with the run, so the first tag push is not the first test of the workflow.
A maintainer with several plugins starts one run per repository at the same time, each in its own sandbox, and reviews a pull request per plugin rather than editing the same workflow by hand in each.
Frequently asked questions
Why are the asset names fixed?
Obsidian's community plugin installer downloads main.js, manifest.json and styles.css from the release by those exact names. The build writes the bundle to build/main.js, so the workflow uploads it under the name main.js, not the path.
What happens if I push a tag without bumping the manifest?
The job fails before creating anything, with a message that names the tag and the version manifest.json holds. Bump the version with the shortened release script, push the commit, then retag.
Will it still publish to npm?
Only if the repository has an NPM_TOKEN secret; the pull request describes the one step that would use it. Without the secret the workflow only creates the GitHub release, and npm publish stays a manual command.
Does the docs deploy still happen?
Yes. documentation.yml listens for release.published, and publishing the draft fires that event exactly as the old script's gh release create did.
More Obsidian plugin jobs
The same job on other stacks
- Add a Release Workflow for a Textual App (Textual)
- Add a Release Workflow With Prebuilt Binaries to a Tokio Server (Tokio)
- Add a Release Workflow for a VS Code Extension (VS Code extension)