update-docs

A Forgejo Action that creates structured issues to trigger an AI agent to review and update repository documentation after recent changes.

How It Works

1. Detects changes — gathers recent commits and changed files based on the trigger type (push, PR, schedule, or manual)
2. Skips if idle — exits early when no changes are detected, or when only doc files changed (prevents feedback loops)
3. Creates an issue or comments on a PR — on push/schedule/dispatch, creates a labeled issue; on pull_request, comments directly on the PR
4. Agent takes over — your agent receives the mention, reviews the docs, and updates them in context (on the PR branch, via new PR, or direct push)

Requirements

The runner environment must have these tools available:

• git
• curl
• jq

The example workflow uses node:22-slim and installs all three in a setup step. Any Debian-based image works.

Usage

Copy example-workflow.yml to your repo as .forgejo/workflows/update-docs.yml, then customize as needed:

- uses: https://git.brads.house/actions/update-docs@v1
  with:
    docs: README.md, CONTRIBUTING.md, docs/setup.md
    agent: intern
    create-pr: true

Real-World Example

This repository uses the action on itself — see .forgejo/workflows/update-docs.yml for a minimal setup that:

• Triggers on pushes to main (ignoring doc-only changes)
• Uses default settings (README.md, agent=intern)
• Pushes directly to main (create-pr: false) instead of opening a PR

This is a working reference you can copy and adapt.

Inputs

Input	Default	Description
docs	README.md	Comma-separated list of doc files to review
agent	intern	Forgejo username to mention and assign
create-pr	true	true = agent opens a PR; false = agent pushes to main
token	${{ github.token }}	Auth token for Forgejo API (automatic token works by default)

Trigger Behavior

The action adapts its context gathering based on how the workflow was triggered:

Trigger	What it does
push	Collects diff between before/after SHAs. Skips if only doc files changed (loop prevention). Creates an issue with descriptive title from first commit.
pull_request	Fetches PR changed files via API. Comments on the PR instead of creating an issue — agent pushes doc updates to the PR branch.
schedule	Collects commits since the last update-docs issue (or 7 days if none found). Creates an issue with descriptive title from first commit.
workflow_dispatch	Thorough review mode — performs a full documentation review of the entire codebase instead of scoping to recent changes. Does not skip on empty changesets. Creates an issue titled "full documentation review".

Issue Titles

When creating issues (non-PR triggers), the action generates descriptive titles using the first commit's subject line plus a short date:

docs: fix: descriptive issue titles and explicit Closes #N for all paths (03/10)
docs: update API documentation (03/15)

For manual triggers (workflow_dispatch), the title is always:

docs: full documentation review (MM/DD)

Titles are truncated at 80 characters for scannability. If no commits are found, it falls back to docs: review documentation (MM/DD).

Auto-Close Behavior

The action includes instructions for the agent to auto-close the issue in all cases:

• No changes needed: Agent closes the issue with a comment explaining that the documentation is already current
• Changes made via PR (create-pr: true): Agent includes Closes #N in the PR description so the issue auto-closes when the PR merges
• Changes made via direct push (create-pr: false): Agent includes Closes #N in the commit message so the issue auto-closes on push
• Pull request trigger: Agent pushes to the PR branch; issue tracking is not applicable

Examples

Minimal — single doc file, default agent

- uses: https://git.brads.house/actions/update-docs@v1

Multiple doc files

- uses: https://git.brads.house/actions/update-docs@v1
  with:
    docs: README.md, CONTRIBUTING.md, docs/api.md

Direct push instead of PR

- uses: https://git.brads.house/actions/update-docs@v1
  with:
    create-pr: false

Custom agent username

- uses: https://git.brads.house/actions/update-docs@v1
  with:
    agent: my-docs-bot

Label

The action creates an update-docs label (color #0075ca) on first run. Subsequent runs reuse the existing label. This label is also used to find the last run date on schedule/manual triggers.

Loop Prevention

The action avoids feedback loops (agent updates docs → push triggers action → new issue → agent responds → ...) in two ways:

1. Action-level: on push, if the only changed files are the doc files being tracked (from the docs input), the action skips with a notice
2. Workflow-level: the example workflow uses paths-ignore to prevent the workflow from even running on doc-only pushes

Early Exit

If no changes are detected (no new commits, no changed files), the action exits cleanly without creating an issue. This prevents duplicate or empty issues on scheduled runs when the repo hasn't changed.

Exception: Manual triggers (workflow_dispatch) never skip, even when no changes are detected, because they're intended for thorough review on-demand.