GitHub Actions for Neovim Plugins

Reusable GitHub Actions and workflows for Neovim plugin development.

Neovim Action

Composite action to install Neovim with caching and optional mini.nvim.

Usage

- uses: thenoetrevino/github/neovim@main
  with:
    version: "stable"      # optional: stable, nightly, or specific version
    mini-nvim: "true"      # optional: install mini.nvim for doc generation

Reusable CI Workflow

Complete CI workflow for Neovim plugins with:

• StyLua formatting check
• Debug message detection (dd() calls)
• Test execution (via plenary or custom script)
• Documentation generation with mini.doc
• Release automation with release-please (the Gitea port in noe.trevino/gitea-release-please-action)

Usage

In your plugin's .forgejo/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: write
  pull-requests: write

jobs:
  ci:
    uses: noe.trevino/ci/.forgejo/workflows/nvim-plugins-ci.yml@main
    secrets: inherit
    with:
      plugin: your-plugin-name
      repo: yourusername/your-plugin
      docs: true      # optional: enable minidoc generation (default: true)
      release: true   # optional: enable release-please (default: true)

Requirements

For documentation generation, your plugin needs:

• scripts/minidoc.lua - Script that runs mini.doc generation

Example scripts/minidoc.lua:

local MiniDoc = require("mini.doc")
_G.MiniDoc = MiniDoc  -- Required for @eval directives

local files = {
    "lua/your-plugin/init.lua",
    "lua/your-plugin/config.lua",
}

MiniDoc.generate(files, "doc/your-plugin.txt")

For tests, either:

• scripts/test.lua - Custom test script
• tests/ directory with plenary tests and tests/minimal_init.lua

Smith: AI jobs for issues and pull requests

smith.yml is a reusable workflow with six jobs. They run the Claude Code CLI and act as the smith account. Each job is off until the caller turns it on.

Input	Event	What it does
pr-labels	PR opened	adds 1-3 existing labels
pr-description	PR opened	comments a summary when the PR text is short (pr-description-min, default 200)
pr-closer	PR opened	adds Closes #N lines for the issues the PR resolves
issue-labels	issue opened	adds 1-3 existing labels
review	PR opened	posts a review with inline comments and a score; review-paths limits it to some files
mention	@smith in an issue, a PR or a comment	answers, and pushes changes (on an issue: to smith/issue-N with a new PR)

@smith in an inline review comment: smith answers in that thread. After it pushes, a second, independent pass checks each thread against the code and gives a confidence. At resolve-confidence (default 80) or more, smith resolves the thread; below it, smith mentions the reviewer to check.

@smith plan writes a plan (goal, numbered steps, tests, open questions) and changes no code. Reply with changes and @smith plan again to revise it. @smith go builds the newest plan: on a PR it pushes to the PR branch; on an issue it pushes to smith/issue-N, opens a PR and asks you to review it.

After every push, a separate check reads the open todo items (task list boxes) in the issue or PR text, the plan and the other comments, and ticks each one that the new code proves done (resolve-confidence). The reply lists what it ticked and what is still open.

persona: agent-smith gives replies, plans and the weekly email the voice of Agent Smith ("Good evening, Mr. Trevino."); set addressee for the name. Reviews, labels and the confidence lines stay plain.

Claude runs in the dontAsk permission mode: it can use only the tools on the job's list. To let @smith run your tests or build, add the commands to mention-tools, for example mention-tools: "Bash(npm test:*),Bash(npm run build:*)".

Other inputs: model (default haiku for labels, sonnet for the rest), instructions (extra project rules for all prompts), mention-tools (extra allowed tools, for example Bash(npm test:*)), mention-max-turns, resolve-confidence, persona, addressee, trigger, ci-ref, claude-version.

Usage

In the repo's .forgejo/workflows/smith.yml:

name: Smith

on:
  pull_request:
    types: [opened]
  issues:
    types: [opened]
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  smith:
    uses: noe.trevino/ci/.forgejo/workflows/smith.yml@main
    secrets: inherit
    with:
      pr-labels: true
      pr-description: true
      pr-closer: true
      issue-labels: true
      review: true
      mention: true

Pin a commit for stable behaviour: use the same commit in @<sha> and in ci-ref: <sha>. With @main, both follow main.

Requirements

• Secrets, set on noe.trevino and on TNT-Software, so all repos of these owners have them:
  • CLAUDE_CODE_OAUTH_TOKEN (claude setup-token)
  • SMITH_TOKEN: a token of the smith account
  • SMITH_PASSWORD: the password of smith, only to resolve review threads (the API cannot; forge resolve signs in to the web page)
• smith needs write access to the repo: it is in the Bots team of TNT-Software; for a personal repo, add smith as a collaborator (Write).
• Only the repo owner, members of the owning org and collaborators can start the mention job (forge permission). PRs from forks get no secrets, so the PR jobs skip them.

Weekly email

smith-weekly.yml (in this repo) sends one email every Sunday at 23:00 UTC about all repos of noe.trevino and TNT-Software: what was merged, what failed, what waits. smith/digest collects the facts, Claude writes the email in the Agent Smith voice, and smith/send-mail sends it through Resend. Run it by hand from the Actions page. Secrets of this repo: SMITH_READ_TOKEN (read-only token of noe.trevino), SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, MAIL_FROM, MAIL_TO.

forge

smith/forge is the Forgejo API client that the jobs and the agent use (forge --help). Examples:

forge labels
forge pr diff 12 --numbered        # old and new line numbers for review comments
forge review-check 12 review.json  # are all comments on diff lines?
forge review 12 review.json        # post; comments off the diff move into the body
forge context 12                   # issue/PR, comments, reviews, files as markdown

Tests: python3 -m unittest discover -s smith.