obsidian-ci-integration

Obsidian CI Integration

Overview

GitHub Actions workflows for Obsidian plugin development: build validation on every push, automated releases when you tag, version-bump scripting, manifest.json validation, and BRAT beta channel support.

Prerequisites

• GitHub repository with an Obsidian plugin
• Working local build (npm run build produces main.js)
• manifest.json and versions.json in repo root
• GitHub Actions enabled on the repository

Instructions

Step 1: Create Build Workflow

# .github/workflows/build.yml
name: Build Plugin
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Build plugin
        run: npm run build

      - name: Verify build output
        run: |
          if [ ! -f main.js ]; then
            echo "ERROR: main.js not found after build"
            exit 1
          fi
          echo "main.js size: $(wc -c < main.js) bytes"

      - name: Validate manifest.json
        run: |
          node -e "
            const m = require('./manifest.json');
            const required = ['id', 'name', 'version', 'minAppVersion', 'description', 'author'];
            const missing = required.filter(f => !m[f]);
            if (missing.length) {
              console.error('Missing manifest fields:', missing.join(', '));
              process.exit(1);
            }
            console.log('manifest.json valid:', m.id, 'v' + m.version);
          "

Step 2: Create Release Workflow

# .github/workflows/release.yml
name: Release Plugin
on:
  push:
    tags:
      - '*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm ci
      - run: npm run build

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          files: |
            main.js
            manifest.json
            styles.css
          draft: false
          generate_release_notes: true

Step 3: Create Version Bump Script

// version-bump.mjs
import { readFileSync, writeFileSync } from 'fs';

const targetVersion = process.env.npm_package_version;

// Update manifest.json
const manifest = JSON.parse(readFileSync('manifest.json', 'utf8'));
const { minAppVersion } = manifest;
manifest.version = targetVersion;
writeFileSync('manifest.json', JSON.stringify(manifest, null, '\t'));

// Update versions.json — maps plugin version to minimum Obsidian version
const versions = JSON.parse(readFileSync('versions.json', 'utf8'));
versions[targetVersion] = minAppVersion;
writeFileSync('versions.json', JSON.stringify(versions, null, '\t'));

console.log(`Bumped to ${targetVersion} (minAppVersion: ${minAppVersion})`);

Step 4: Wire Version Bump into package.json

{
  "scripts": {
    "build": "node esbuild.config.mjs",
    "dev": "node esbuild.config.mjs --watch",
    "version": "node version-bump.mjs && git add manifest.json versions.json"
  }
}

Now npm version patch (or minor/major) runs the bump script automatically.

Step 5: Add Manifest Validation Workflow

# .github/workflows/validate.yml
name: Validate Plugin
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check manifest/versions consistency
        run: |
          node -e "
            const manifest = require('./manifest.json');
            const versions = require('./versions.json');
            const pkg = require('./package.json');
            let fail = false;

            if (manifest.version !== pkg.version) {
              console.error('Version mismatch: manifest=' + manifest.version + ' package=' + pkg.version);
              fail = true;
            }

            if (!versions[manifest.version]) {
              console.error('versions.json missing entry for ' + manifest.version);
              fail = true;
            }

            if (fail) process.exit(1);
            console.log('All versions consistent: ' + manifest.version);
          "

Step 6: BRAT Beta Support

Add a beta-manifest.json for BRAT beta testers:

{
  "id": "your-plugin-id",
  "name": "Your Plugin (Beta)",
  "version": "1.2.0-beta.1",
  "minAppVersion": "1.5.0",
  "description": "Beta channel — install via BRAT",
  "author": "Your Name"
}

Beta users install via BRAT by entering your GitHub repo URL. BRAT fetches the latest release (including pre-releases) automatically — no submission to the community repo needed.

Output

• .github/workflows/build.yml — validates build on every push/PR
• .github/workflows/release.yml — creates GitHub release with main.js, manifest.json, styles.css on tag push
• .github/workflows/validate.yml — checks version consistency across manifest, package.json, and versions.json
• version-bump.mjs — keeps manifest.json and versions.json in sync with package.json version
• Optional beta-manifest.json for BRAT beta channel

Error Handling

Error	Cause	Solution
main.js not found	Build script doesn't output to root	Check esbuild outfile points to ./main.js
Release has no assets	Tag pushed before build	Let the release workflow handle the build, don't attach manually
Version mismatch	Forgot npm version	Run npm version patch instead of editing manifest by hand
BRAT not picking up beta	No pre-release on GitHub	Create release and check "pre-release" checkbox
npm ci fails	No lockfile	Commit package-lock.json to the repo
Permission denied on release	Missing contents: write	Add permissions block to release job

Examples

Tag and Release a New Version

set -euo pipefail
# Bump, commit, tag, push — release workflow fires automatically
npm version patch
git push origin main --tags

Manual Build Verification

set -euo pipefail
npm ci
npm run build
test -f main.js && echo "Build OK: $(wc -c < main.js) bytes" || echo "FAIL: main.js missing"
node -e "const m=require('./manifest.json'); console.log(m.id, 'v'+m.version)"

Release with Changelog

# In release.yml, replace generate_release_notes with a body:
- name: Create GitHub Release
  uses: softprops/action-gh-release@v2
  with:
    files: |
      main.js
      manifest.json
      styles.css
    body: |
      ## Changes
      - Feature: Added X
      - Fix: Resolved Y

Resources

• Obsidian Plugin Releasing Guide
• GitHub Actions Documentation
• BRAT Plugin
• softprops/action-gh-release

Next Steps

For publishing to the community plugin directory, see obsidian-deploy-integration. For pre-release quality checks, see obsidian-prod-checklist.