InkLoom Docs Action

Automatically generate and update documentation using AI. Keeps your docs in sync with code changes.

Usage

name: Update Documentation
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: inkloom-io/docs-action@v1
        with:
          api-key: ${{ secrets.INKLOOM_API_KEY }}
          project-id: ${{ secrets.INKLOOM_PROJECT_ID }}
          output: pr
          auto-deploy: "true"
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input	Required	Default	Description
api-key	Yes	—	InkLoom API key
project-id	Yes	—	InkLoom project ID
openrouter-key	No	—	OpenRouter API key (or set OPENROUTER_API_KEY env var)
mode	No	fast	AI mode: extended (higher quality) or fast (faster)
model	No	—	AI model to use. Uses project default if empty.
output	No	pr	Output mode: pr, branch, or direct
auto-deploy	No	true	Auto-deploy to production on merge (pr/branch) or immediately (direct)
docs-path	No	docs	Path to existing docs directory
config-path	No	.inkloom/docs.yml	Path to config file
description	No	—	Product description (overrides config)
budget	No	—	Max budget in cents for AI generation

Behavior Matrix

output	auto-deploy: true	auto-deploy: false
pr	Preview deploy on PR. Production deploy on merge.	Preview deploy on PR. Merge syncs to InkLoom, no production deploy.
branch	Preview deploy on MR. Production deploy on MR merge in InkLoom.	Preview deploy on MR. No production deploy.
direct	Push to InkLoom + production deploy immediately.	Push to InkLoom only. No deploy.

Preview deploys and comments always happen for pr and branch modes.

Outputs

Output	Description
pages-generated	Number of pages generated or updated
job-id	InkLoom generation job ID
preview-url	Preview deployment URL
cost-cents	Estimated cost in cents
pr-url	URL of created PR (when output mode is pr)

How It Works

On Pull Requests

1. Analyzes git diff to find changed files
2. Filters through .inkloom/docs.yml scope patterns
3. If no doc-relevant changes, posts a comment and exits
4. AI engine generates/updates documentation
5. Commits docs to the PR branch
6. Pushes pages to InkLoom and triggers preview deployment
7. Posts a PR comment with results, cost summary, and preview link

On Push to Main

1. AI engine generates documentation for the full codebase
2. Pages are pushed to InkLoom via the bulk API
3. If auto-deploy is true, a production deployment is triggered

Configuration

Create .inkloom/docs.yml in your repository root:

product:
  description: "Short product description"
  audience: public

scope:
  include: ["src/**", "lib/**", "README.md"]
  exclude: ["**/*.test.*", "vendor/**"]

ai:
  mode: fast
  max_pages: 50

action:
  output: pr
  autoDeploy: true

Controlling Costs

• Use mode: fast (default) for incremental updates — cheaper, faster
• Use mode: extended for comprehensive generation — higher quality, more expensive
• Set a budget input to cap spending per run
• Use the cost-cents output to track spending across runs

Secrets Setup

Add these secrets in your repository settings (Settings → Secrets and variables → Actions):

1. INKLOOM_API_KEY: Generate from your InkLoom project settings → API Keys
2. INKLOOM_PROJECT_ID: Found in your InkLoom project URL or settings
3. OPENROUTER_API_KEY: Get from OpenRouter (or use InkLoom-managed credits)

License

MIT