CI/CD Workflows¶

Understand the automated validation and deployment pipelines that ensure plugin quality and documentation availability.

Overview¶

The repository uses four GitHub Actions workflows:

Validate Plugins¶

File: .github/workflows/validate-plugins.yml Trigger: PR or push to main/develop (when plugins/** changes)

This is the main validation pipeline. It runs four jobs in parallel:

graph TD
    A["validate-plugins.yml"] --> B["validate-structure"]
    A --> C["validate-documentation"]
    A --> D["security-scan"]
    A --> E["test-plugins"]
    B --> F["summary"]
    C --> F
    D --> F
    E --> F
    F --> G{All passed?}
    G -->|Yes| H["✅ PR can merge"]
    G -->|No| I["❌ PR blocked"]

Job: validate-structure¶

Checks the structural integrity of all plugins:

Example output:

1
2
3
4
5

Checking plugins/git-workflow/.claude-plugin/plugin.json
✅ Valid: plugin.json (name: git-workflow, version: 2.0.0)

Checking plugins/git-workflow/commands/commit.md
✅ Valid command: commit.md

Job: validate-documentation¶

Ensures documentation quality:

• Verifies every plugin has a README.md
• Checks that README files contain sections (headers)
• Runs markdown link validation (broken link detection)

Job: security-scan¶

Scans for security issues:

• Trivy filesystem scan for HIGH/CRITICAL vulnerabilities
• Pattern-based secret detection (API keys, passwords, secrets)
• Scans all files under plugins/

Job: test-plugins¶

Validates plugin loading capability:

• Verifies each plugin directory can be loaded
• Checks structural prerequisites for Claude Code compatibility

Job: summary¶

Aggregates results from all jobs:

• Reports status of each validation job
• Fails the pipeline if structure, documentation, or plugin tests fail
• Security scan failures are logged but don't block merging

Branch Protection¶

File: .github/workflows/branch-protection.yml Trigger: PR to main or develop

Enforces development standards for all pull requests.

Checks Performed¶

Branch Naming Validation¶

For PRs to develop, the source branch must use one of these prefixes:

Commit Message Validation¶

Checks that commits follow the Emoji Conventional Commits format:

1

<emoji> <type>(<optional scope>): <description>

Accepted types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert, security, i18n, a11y, deps

Skipped: Merge commits and release commits are ignored.

Examples:

1
2
3
4

✅ ✨ feat: Füge Benutzer-Dashboard hinzu
✅ 🐛 fix(auth): Behebe Login-Fehler
✅ 📚 docs: Aktualisiere README
✅ Merge branch 'main' into develop   (skipped)

PR Description Check¶

Warns if the PR description is shorter than 50 characters. Encourages detailed descriptions with:

• What changes were made
• Why the changes were necessary
• How the changes were tested

PR Size Validation¶

Warns if a PR has more than 1,000 changes. Suggests breaking large PRs into smaller, focused ones.

Approval Requirements¶

Both main and develop require at least 1 approval before merging.

Deploy Documentation¶

File: .github/workflows/deploy-docs.yml Trigger: Push to main (specific paths) or manual dispatch

Automatically builds and deploys documentation to GitHub Pages.

Trigger Paths¶

The workflow runs when these files change on main:

• docs/** - Any documentation file
• mkdocs.yml - MkDocs configuration
• plugins/*/README.md - Plugin READMEs (used via symlinks)
• .github/workflows/deploy-docs.yml - The workflow itself

Build Process¶

graph LR
    A["Push to main"] --> B["Checkout with full history"]
    B --> C["Install Python + uv"]
    C --> D["Install dependencies"]
    D --> E["mkdocs gh-deploy"]
    E --> F["GitHub Pages updated"]

1. Checkout with full git history (needed for git-revision-date-localized plugin)
2. Install Python 3.13.1 and uv package manager
3. Sync dependencies from pyproject.toml
4. Build and deploy using mkdocs gh-deploy --force --clean
5. Summary with deployment URL and commit reference

Manual Deployment¶

Trigger a deployment manually from the GitHub Actions UI using workflow_dispatch.

PR Labels¶

File: .github/workflows/pr-labels.yml Trigger: PR events

Automatically labels PRs based on content:

By Changed Files¶

By PR Size¶

By Commit Type¶

Other Workflows¶

Greetings (greetings.yml)¶

Welcomes first-time contributors automatically when they open their first issue or PR.

Stale (stale.yml)¶

Manages inactive issues and PRs:

• Issues: Marked stale after 60 days of inactivity, closed after 7 more days
• PRs: Marked stale after 30 days of inactivity, closed after 7 more days

Running CI Locally¶

You can simulate CI checks locally using the core plugin:

1
2
3
4
5
6
7

# Load the core plugin
claude --plugin-dir ./plugins/core

# Run validation
/check-commands
/check-agents
/run-ci

Or run checks manually:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Validate JSON files
find plugins -name "plugin.json" -exec jq empty {} \;

# Check directory structure
for dir in plugins/*/; do
  test -f "$dir/.claude-plugin/plugin.json" && echo "✅ $dir" || echo "❌ $dir"
done

# Build documentation
uv run mkdocs build --strict

Related Resources¶

• Testing - Test plugins locally
• Contributing - Submission workflow
• Architecture - Repository structure
• Best Practices - Quality guidelines