Agent Skills: Obsidian Plugin Deploy Integration

Obsidian Plugin Deploy Integration

Overview

Release and distribute Obsidian plugins through multiple channels: the official community plugin directory, GitHub releases, BRAT beta testing, and manual installation. Covers the full lifecycle from building release assets to submitting your PR to the obsidian-releases repo.

Prerequisites

• Obsidian plugin with main.ts, manifest.json, and styles.css (if applicable)
• GitHub repository for your plugin (public)
• gh CLI authenticated (gh auth status)
• Plugin passes obsidian-prod-checklist validation

Instructions

Step 1: Build Release Assets

set -euo pipefail
# Clean build for production
rm -f main.js
npm ci
npm run build

# Verify the three release files exist
for f in main.js manifest.json; do
  test -f "$f" || { echo "MISSING: $f"; exit 1; }
done
test -f styles.css && echo "styles.css included" || echo "No styles.css (OK if no custom styles)"

echo "Release assets ready"

Step 2: Version Bump with version-bump.mjs

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

const targetVersion = process.env.npm_package_version;

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

// Sync versions.json — maps each plugin version to its 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} (requires Obsidian >= ${minAppVersion})`);

Wire it into package.json so npm version triggers it automatically:

{
  "scripts": {
    "version": "node version-bump.mjs && git add manifest.json versions.json"
  }
}

Step 3: Create GitHub Release

set -euo pipefail
# Bump version, commit, and tag
npm version patch   # or minor / major
git push origin main --tags

# Create release with assets (or let the release workflow from obsidian-ci-integration handle it)
gh release create "$(node -p 'require("./manifest.json").version')" \
  main.js manifest.json styles.css \
  --title "v$(node -p 'require("./manifest.json").version')" \
  --generate-notes

The release must include these files at the root level (not nested in folders):

• main.js — compiled plugin code
• manifest.json — plugin metadata
• styles.css — only if your plugin has custom styles

Step 4: Submit to Community Plugins

First-time submission requires a PR to the obsidian-releases repo:

set -euo pipefail
# Fork and clone the releases repo
gh repo fork obsidianmd/obsidian-releases --clone
cd obsidian-releases

# Add your plugin entry to community-plugins.json
node -e "
  const fs = require('fs');
  const plugins = JSON.parse(fs.readFileSync('community-plugins.json', 'utf8'));
  const entry = {
    id: 'your-plugin-id',
    name: 'Your Plugin Name',
    author: 'Your Name',
    description: 'Brief description of what your plugin does.',
    repo: 'your-github-username/your-plugin-repo'
  };

  // Insert alphabetically by id
  const idx = plugins.findIndex(p => p.id.localeCompare(entry.id) > 0);
  plugins.splice(idx >= 0 ? idx : plugins.length, 0, entry);
  fs.writeFileSync('community-plugins.json', JSON.stringify(plugins, null, '\t') + '\n');
  console.log('Added', entry.id, 'at index', idx >= 0 ? idx : plugins.length);
"

git checkout -b add-your-plugin-id
git add community-plugins.json
git commit -m "Add your-plugin-id"
git push origin add-your-plugin-id
gh pr create --repo obsidianmd/obsidian-releases \
  --title "Add your-plugin-id" \
  --body "## Plugin submission

- **Repo:** https://github.com/your-username/your-plugin-repo
- **Description:** Brief description
- **I have tested on:** Desktop (macOS/Windows/Linux), Mobile (iOS/Android)"

Review requirements the Obsidian team checks:

• manifest.json has all required fields (id, name, version, minAppVersion, description, author)
• id in manifest matches the id in your community-plugins.json entry
• No console.log in production code
• No eval() or dynamic code execution
• No remote code loading at runtime
• Plugin works on mobile if isDesktopOnly is not set

Step 5: BRAT for Beta Testing

Before submitting to community plugins, test your distribution via BRAT:

1. Users install BRAT from community plugins
2. In BRAT settings, they click "Add Beta Plugin"
3. They enter your GitHub repo URL: your-username/your-plugin-repo
4. BRAT installs the latest release (including pre-releases)

To push a beta:

set -euo pipefail
npm version prerelease --preid=beta
git push origin main --tags
gh release create "$(node -p 'require("./manifest.json").version')" \
  main.js manifest.json styles.css \
  --title "Beta: v$(node -p 'require("./manifest.json").version')" \
  --prerelease

Step 6: Manual Installation

For users who prefer manual install or for testing outside BRAT:

set -euo pipefail
# Users copy files to their vault's plugin directory
VAULT_PATH="/path/to/vault"
PLUGIN_ID="your-plugin-id"
DEST="$VAULT_PATH/.obsidian/plugins/$PLUGIN_ID"

mkdir -p "$DEST"
cp main.js manifest.json "$DEST/"
test -f styles.css && cp styles.css "$DEST/"

echo "Installed to $DEST — restart Obsidian and enable in Settings > Community Plugins"

Output

• Production main.js, manifest.json, and styles.css as GitHub release assets
• version-bump.mjs script for consistent versioning across all config files
• PR to obsidianmd/obsidian-releases for community plugin listing
• BRAT-compatible releases for beta testing
• Manual install path for direct distribution

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | Plugin not loading after install | id in manifest doesn't match directory name | Ensure the plugin folder name matches manifest.json id | | Build output missing | esbuild outfile misconfigured | Set outfile: 'main.js' in esbuild config | | Community PR rejected | Guidelines violation | Check Plugin Guidelines | | Version mismatch | Forgot to run version-bump | Use npm version which triggers the script automatically | | BRAT can't find releases | No GitHub release created | BRAT needs actual GitHub releases, not just tags | | gh release create fails | Not authenticated | Run gh auth login first | | Manual install doesn't load | Missing manifest.json | All three files must be in the plugin directory |

Examples

Update an Existing Community Plugin

Already listed? Just create a new release — Obsidian auto-detects new versions:

set -euo pipefail
npm version patch
git push origin main --tags
# Release workflow creates the GitHub release automatically

Users see the update in Settings > Community Plugins > Check for updates.

Check Your Submission Status

set -euo pipefail
# See if your plugin is already in the directory
gh pr list --repo obsidianmd/obsidian-releases --search "your-plugin-id" --state all

Resources

• Obsidian Plugin Submission Guide
• Plugin Guidelines
• Community Plugins Repo
• BRAT Plugin
• Sample Plugin Template

Next Steps

For event handling patterns, see obsidian-webhooks-events. For pre-release quality validation, see obsidian-prod-checklist.