Skip to content

Developer Releases and CI

Vivek Sarin edited this page Nov 18, 2026 · 4 revisions

Releases and CI

This page covers build artifacts, release checks, and GitHub Actions. For local setup, see Setup and build.

Build a release locally

From the repository root:

make release-build
make release-check TAG=1.0.2

Replace 1.0.2 with the intended version. make release-build runs npm ci and builds the plugin. Neither optional editor runtime is included in the release.

The files published by the release workflow are:

File Purpose
dist/plugin/main.js Core Obsidian plugin
dist/plugin/manifest.json Plugin metadata and minimum Obsidian version
dist/plugin/styles.css Plugin styles

When users enable an add-on, the plugin downloads draw.io from its upstream GitHub release or Monaco from its pinned npm package. The tag must be plain semver such as 1.0.2 and must equal the manifest.json version.

Version and artifact checks

scripts/check-release.mjs verifies:

  • The tag is plain major.minor.patch, with no v prefix.
  • The tag equals manifest.json's version.
  • The manifest ID uses lowercase letters, digits, and hyphens, and does not contain obsidian.
  • The manifest description ends with a period.
  • versions.json maps the release version to the manifest's minAppVersion.
  • All three release files exist.

Keep package metadata consistent when changing versions. Passing this script is a repository release check, not confirmation of acceptance into Obsidian's community catalog.

Publish a release

Publishing warning: pushing a version tag triggers a public GitHub release. Complete the local checks before pushing the tag.

  1. Update the version metadata and changelog.
  2. Commit and push the release changes.
  3. Create a plain version tag matching manifest.json.
  4. Push that tag to GitHub.
  5. Check the release workflow and attached files.

.github/workflows/release.yml runs on tags matching *.*.*. It uses Node 24, lints and runs unit tests, builds the plugin, and validates the tag. It attests the three artifacts and creates a release with notes from CHANGELOG.md. If a release already exists for the tag, it uploads the artifacts without changing the release notes or publication state. Upload fails if an asset with the same name already exists; it does not replace existing assets.

The release job does not run the desktop E2E suite; check the separate E2E workflow before publishing.

Continuous integration

Workflow Trigger Checks
lint.yml - Node.js build Pushes and pull requests on all branches Locked install, build, lint, and unit tests on Node 22.x and 24.x
e2e.yml - E2E (Obsidian) Pushes and pull requests on all branches Desktop smoke and settings tests on Node 22.x with Xvfb
release.yml - Release Obsidian plugin Version-tag pushes Release build, validation, provenance, and publication
codeql.yml - CodeQL Advanced Pushes and pull requests targeting main, plus a weekly schedule CodeQL analysis of GitHub Actions workflows
dependency-review.yml - Dependency review Pull requests targeting main Dependency-change review
scorecard.yml - Repository scorecard Pushes to main, plus a weekly schedule OpenSSF Scorecard analysis

The E2E job runs on Ubuntu with a 30-minute job limit. It installs:

sudo apt-get update
sudo apt-get install -y xvfb libnss3 libgbm1 libgtk-3-0 libasound2t64 libsecret-1-0 libxss1
npm ci
xvfb-run -a npm run test:e2e

On failure, the workflow tries to upload logs under .obsidian-cache/**/*.log and screenshots under e2e/**/screenshots/**. Missing files do not fail that upload, so a failed run may have no artifact. Consult the job log as well.

Run workflows locally with gh act

The Makefile provides helpers for GitHub CLI with the gh-act extension and Docker:

Command Purpose
make act-install Installs or upgrades the extension
make ci-list Lists workflow jobs
make ci-dry-run Dry-runs build and release workflows
make ci-lint Runs the build job; defaults to Node 24.x
make ci-release-build Runs release build steps without publication
make ci-release-dryrun Dry-runs the release workflow
make ci-all Runs build checks, then release build steps

Use ACT_NODE=22.x to select the other build matrix entry. ACT_RUNNER selects the Docker runner image; the default is catthehacker/ubuntu:act-latest.

If a local workflow needs credentials, make act-secrets creates a .secrets template only when none exists. Keep real tokens out of Git and chat. The helpers pass this file only when it exists; ACT_SECRETS can select another path.

Local act runs skip tag validation, attestation, and publication because they lack a real release tag and GitHub OIDC identity. Run make release-check TAG=<version> separately.

These helpers do not include the desktop E2E job in make ci-all. Run make test-e2e separately.

Related pages

Clone this wiki locally