Plugin System

Overview

Plugins are built-in features that extend sley's core functionality. Unlike extensions (which are external scripts), plugins are compiled into the binary and provide deep integration with version bump logic.

Available Plugins

Plugin	Type	Description	Default
commit-parser	analyzer	Analyzes conventional commits to determine bump type	Enabled
tag-manager	automation	Automatically creates git tags synchronized with bumps	Disabled
version-validator	validator	Enforces versioning policies and constraints	Disabled
dependency-check	sync	Validates and syncs versions across multiple files	Disabled
changelog-parser	analyzer	Infers bump type from CHANGELOG.md entries	Disabled
changelog-generator	generator	Generates changelog from conventional commits	Disabled
release-gate	gate	Pre-bump validation (clean worktree, branch, WIP)	Disabled
audit-log	logger	Records version changes with metadata to a log file	Disabled

INFO

The "Default" column shows which plugins are active when running sley without a .sley.yaml configuration file. When using sley init --yes, a recommended starting configuration is created with both commit-parser and tag-manager enabled.

Quick Start

Enable plugins in your .sley.yaml:

plugins:
  # Analyze commits for automatic bump type detection
  commit-parser: true

  # Automatically create git tags after bumps
  tag-manager:
    enabled: true
    prefix: "v"
    annotate: true
    push: false

  # Enforce versioning policies
  version-validator:
    enabled: true
    rules:
      - type: "major-version-max"
        value: 10
      - type: "branch-constraint"
        branch: "release/*"
        allowed: ["patch"]

  # Sync versions across multiple files
  dependency-check:
    enabled: true
    auto-sync: true
    files:
      - path: "package.json"
        field: "version"
        format: "json"

Execution Order

During a version bump, extensions and plugins execute in a specific order:

sley bump patch

Pre-bump ExtensionsCan abort

Extensions (pre-bump)Custom scripts run first, can modify .version file. Aborts on failure.

Pre-bump ValidationCan abort

release-gateValidates pre-conditions (clean worktree, branch, WIP)

version-validatorValidates version policy

dependency-checkValidates file consistency

tag-managerValidates tag does not exist

Version Bump

Version file updated.version file is written with new version

Post-bump ActionsNon-blocking

dependency-checkSyncs version to configured files

changelog-generatorCreates changelog entry

audit-logRecords version change to log file

tag-managerCreates git tag

Post-bump ExtensionsNon-blocking

Extensions (post-bump)Custom scripts for notifications, deployments, etc.

Extensions Run First

Pre-bump extensions execute before plugin validations. This allows extensions to set up state (e.g., fetch a version from an external source and update .version) before plugins validate consistency. After pre-bump extensions complete, sley re-reads the .version file to pick up any changes.

When to Use Plugins vs Extensions

Use Plugins When

• Performance matters: Plugins execute in <1ms with native Go performance
• Feature is widely applicable: Common versioning needs across many projects
• Deep integration needed: Requires tight coupling with bump logic or validation
• Built-in reliability required: No external dependencies or installation steps
• Examples: Git tagging, conventional commit parsing, version validation, file syncing

Use Extensions When

• Custom to your workflow: Organization-specific automation or processes
• Requires external tools: Need to call AWS CLI, curl, custom scripts, etc.
• Prototyping new features: Testing ideas before proposing as built-in plugins
• Language-specific needs: Python/Node.js/Ruby tooling integration
• Examples: Custom notification systems, deployment triggers, proprietary tool integration

Plugin vs Extension Comparison

Feature	Plugins	Extensions
Compilation	Built-in, compiled with CLI	External scripts
Performance	Native Go, <1ms	Shell/Python/Node, ~50-100ms
Installation	None required	sley extension install
Configuration	.sley.yaml plugins section	.sley.yaml extensions section
Use Case	Core version logic, validation, sync	Hook-based automation

TIP

Most users will only need plugins. Extensions are for advanced customization and organization-specific workflows.

Common Workflow Patterns

Auto-Bump + Changelog

sley bump auto
# commit-parser analyzes commits -> determines bump type
# changelog-generator creates versioned changelog entry

Auto-Bump + Tag + Push

sley bump auto
# commit-parser analyzes commits -> bump type
# tag-manager validates tag doesn't exist
# Version updated -> tag created and pushed

Full CI/CD Pipeline

sley bump auto
# Pre-bump: version-validator, dependency-check, tag-manager validation
# Bump: commit-parser determines type, version updated
# Post-bump: files synced, changelog generated, tag created

See Also

• Extension System - Create custom automation hooks
• .sley.yaml Reference - Complete plugin configuration reference
• CI/CD Integration - Automate plugins in pipelines
• Usage Guide - Learn how plugins integrate with commands
• Configuration - Configuration methods and precedence
• Troubleshooting - Common plugin issues