AI workflows

One repo of reusable workflows. Consumer repos write thin callers, choose Claude or Codex once, and inherit workflow updates.

dryvist/ai-workflows ships reusable GitHub Actions workflows (on: workflow_call:). The workflow orchestration, provider routing, and rate guards live there. Prompt text comes from the pinned dryvist/ai-llm-prompts catalog. Consumers declare triggers, permissions, and secret forwarding.

Event-triggered workflows

These run on GitHub events. Wire one caller per workflow you want.

Workflow	Trigger	What it does
`issue-triage.yml`	`issues: [opened]`	Categorizes, deduplicates, labels new issues
`issue-resolver.yml`	`issues: [opened]`	Creates a draft PR when the issue is well-scoped and not excluded by labels
`ci-fix.yml`	`workflow_run` of your CI workflow, `conclusion: failure`	Reads the failed log, pushes a fix commit
`project-router.yml`	`issues/pull_request: [opened, labeled]`	Routes items to GitHub Projects with smart field assignment
`post-merge-docs-review.yml`	`push: [main]` → dispatch	After merge, audits docs touched by the commit, creates fix PRs
`post-merge-tests.yml`	`push: [main]` → dispatch	After merge, analyzes the code changes and drafts targeted tests
`issue-linker.yml`	`pull_request: [opened, closed]`	Links open issues to PRs on open; closes resolved issues on merge
`notify-ai-pr.yml`	`pull_request: [opened]` from a bot	Slack notification when an AI-authored PR opens

Scheduled workflows

These run on cron — typically called with schedule: and a manual workflow_dispatch:.

Workflow	Default schedule	What it does
`code-simplifier.yml`	Daily 04:00 UTC	DRY enforcement, dead code removal, drafts PRs
`best-practices.yml`	Weekly Wed 03:00 UTC	Audit creating actionable recommendations
`next-steps.yml`	Daily 05:00 UTC	Analyzes merge momentum, suggests next logical action
`issue-sweeper.yml`	Weekly Mon 06:00 UTC	Scans open issues, comments on progress, closes resolved
`issue-hygiene.yml`	Weekly Mon 07:00 UTC	Detects duplicates, links merged PRs, flags stale issues
`label-sync.yml`	Weekly Sun 05:00 UTC	Syncs canonical labels from the `.github` repo to consumers
`repo-orchestrator.yml`	`workflow_dispatch`	Multi-repo hub-and-spoke dispatcher for ad-hoc operations

How a reusable caller looks

A reusable-workflow caller is the smallest YAML that declares a trigger, sets permissions, and forwards to the upstream:

name: Issue Triage
on:
  issues:
    types: [opened]
permissions:
  contents: read
  id-token: write
  issues: write
jobs:
  run:
    uses: dryvist/ai-workflows/.github/workflows/issue-triage.yml@main
    secrets: inherit

Permission shape varies per workflow — issue-resolver needs pull-requests: write, ci-fix needs actions: read, post-merge-* needs actions: write for the re-dispatch. The canonical caller templates list the exact permission block for each.

How prompts are loaded

The reusable workflows check out the catalog at its pinned release commit, select an asset from automation/, and remove its OKF frontmatter before passing the prompt to the selected model. Local workflow YAML still owns triggers, permissions, publishing, and provider configuration.

Versioning

Per Dependency automation, consumers pin ai-workflows — and every dryvist/* reusable workflow — at @main, never a SHA or version pin. The SemVer tags still exist (@v0.15.1) and release-please keeps bumping them for the changelog and the per-run resolved-SHA audit trail, but callers ride @main so upstream fixes land immediately with no per-repo Renovate PR (the first-party immediate-propagation model). Every org scanner is configured to allow @main — see scanner posture.

Authentication

Reusable .yml workflows select the AI agent through one organization variable: GH_ACTION_AI_AGENT=claude|codex. The default is claude, so existing callers keep their current behavior. Set it to codex once at the organization, repository, or environment level to switch every inherited workflow. Each agent keeps its own credential. Pre-provision both secrets so switching the selector does not require caller edits.

Name	Kind	Purpose
`GH_ACTION_AI_AGENT`	Variable	`claude` or `codex`. Defaults to `claude`.
`GH_ACTION_AI_API_KEY`	Secret	Anthropic API key used when the selector is `claude`.
`OPENAI_API_KEY`	Secret	OpenAI API key used when the selector is `codex`.
`GH_ACTION_AI_BASE_URL`	Variable	Optional Claude-compatible endpoint. Leave empty for direct Anthropic.
`GH_ACTION_AI_MODEL`	Variable	Optional global Claude model default.
`GH_ACTION_AI_MODEL_CODE`	Variable	Optional Claude code tier. Falls back to `GH_ACTION_AI_MODEL`.
`GH_ACTION_AI_MODEL_ISSUES`	Variable	Optional Claude issue tier. Falls back to `GH_ACTION_AI_MODEL`.
`GH_ACTION_AI_MODEL_PLAN`	Variable	Optional Claude planning tier. Falls back to `GH_ACTION_AI_MODEL`.
`GH_ACTION_AI_CODEX_RESPONSES_API_ENDPOINT`	Variable	Optional Codex Responses API endpoint.
`GH_ACTION_AI_CODEX_MODEL`	Variable	Optional Codex model override.
`GH_ACTION_AI_CODEX_EFFORT`	Variable	Optional Codex reasoning-effort override.
`GH_ACTION_AI_CODEX_VERSION`	Variable	Optional Codex CLI version override.

Set them at org level with the GitHub CLI:

gh secret set GH_ACTION_AI_API_KEY --org <your-org>
gh secret set OPENAI_API_KEY --org <your-org>
gh variable set GH_ACTION_AI_AGENT --org <your-org> --body claude

Callers inside the same organization can use secrets: inherit. If a caller maps secrets explicitly, forward both credentials:

secrets:
  GH_ACTION_AI_API_KEY: ${{ secrets.GH_ACTION_AI_API_KEY }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

OAuth tokens are prohibited in unattended CI. A Claude Code subscription token (CLAUDE_CODE_OAUTH_TOKEN) used inside a GitHub Actions workflow violates the Claude Code Terms of Service and risks an account ban — the subscription is intended for interactive sessions only. Use a standard API key (GH_ACTION_AI_API_KEY) instead; it is purpose-built for programmatic access with no ToS concerns.

GitHub Agentic Workflows are retired. The catalog keeps one dormant reference template, but no active repository compiles or runs GH-AW Markdown. Provider details and model configuration live in AUTHENTICATION.md.

Security boundary

The model job does not receive a privileged GitHub App token. It checks out code without persisted credentials and returns structured output or a workspace change. A separate publisher job validates that handoff, mints the short-lived App token, and performs the requested GitHub write. This boundary keeps repository comments, labels, branches, commits, and pull requests deterministic. It also applies to both agents, so changing GH_ACTION_AI_AGENT does not change the workflow’s GitHub permissions. Existing GitHub App secret names remain supported for inherited callers. The GH_APP_CLAUDE_BOT_PRIVATE_KEY and GH_APP_CLAUDE_BOT_ID secrets are distributed through the _github_app_repos anchor, not _claude_bot_repos, so reusable workflows can mint App tokens from consumer repositories.

Where to go next

Getting started

Caller templates for every workflow, with the correct permission blocks.

Patterns

The post-merge dispatch pattern, bot guards, and other recurring shapes.

Authentication

Full GH_ACTION_AI_* reference, provider routing, and model variables.

Prompt catalog

Versioned OKF prompt assets and the immutable consumer pin.

Verification

The e2e runbook for checking a freshly-wired repo end to end.

Issue → PR pipeline on this repo

Exactly which six callers are wired on JacobPEvans/docs and why.

Secret distribution

How GH_ACTION_AI_API_KEY and the App credentials land on each consumer repo.

Infrastructure

Observability

Automation

Event-triggered workflows

Scheduled workflows

How a reusable caller looks

How prompts are loaded

Versioning

Authentication

Security boundary

Where to go next

Getting started

Patterns

Authentication

Prompt catalog

Verification

Issue → PR pipeline on this repo

Secret distribution

​Event-triggered workflows

​Scheduled workflows

​How a reusable caller looks

​How prompts are loaded

​Versioning

​Authentication

​Security boundary

​Where to go next

Getting started

Patterns

Authentication

Prompt catalog

Verification

Issue → PR pipeline on this repo

Secret distribution

Event-triggered workflows

Scheduled workflows

How a reusable caller looks

How prompts are loaded

Versioning

Authentication

Security boundary

Where to go next