RFC: create shared GitHub Actions repo for AI automation

[Bad3r]

Summary

Create a shared GitHub Actions repository for reusable automation used across my repos, focused first on AI-assisted workflows for Claude Code and OpenAI Codex.

The first target should be the Claude workflows currently duplicated under .github/workflows/:

• claude-code-review.yml
• claude-mention-assistant.yml

The shared implementation should use GitHub reusable workflows (workflow_call) as the main consumer interface. A submodule can still be considered later for shared scripts or local tooling, but it should not be the primary mechanism for workflow reuse because GitHub Actions only discovers workflow files from .github/workflows/ in the consuming repo.

Research

I looked for existing repos that centralize Claude Code and OpenAI Codex automation.

Relevant prior art:

• WalletConnect/actions: shared org actions repo with claude/agent and claude/auto-review composite actions wrapping anthropics/claude-code-action.
• oxidian/actions: shared reusable/composite actions repo with OpenAI Codex PR review and a workflow_call reusable workflow.
• drakulavich/iago: GitHub Action plus Claude Code/Codex CLI skill, supporting Anthropic and OpenAI providers behind one action.
• anthropics/claude-code-action: official Claude Code action with mention/review examples and security guidance.
• openai/codex-action: official Codex action with PR review example and sandbox/security guidance.

I did not find a single repo that cleanly centralizes both Claude Code and OpenAI Codex reusable workflows exactly as needed here. The best design is to combine patterns from WalletConnect/actions and oxidian/actions.

Problem

Several repos need the same GitHub Actions behavior:

• Claude PR review workflow.
• Claude mention assistant workflow triggered by @claude.
• Future Codex PR review workflow.
• Common checkout, permissions, model, prompt, and allowed-tool configuration.
• Potentially shared Nix workflows later, such as flake checks or flake update PRs.

Keeping this duplicated in every repo causes drift in:

• Claude/Codex model selection.
• Allowed tool policy.
• Workflow permissions.
• Prompt quality.
• Third-party action versions.
• Security posture.
• Trigger behavior.

Goals

• Create a central repo for reusable GitHub Actions workflows and composite actions.
• Expose high-level reusable workflows through .github/workflows/*.yml with on: workflow_call.
• Keep per-repo workflow files small and declarative.
• Document required secrets, permissions, inputs, and example caller workflows.
• Version the shared workflows with stable tags such as v1.
• Migrate this repo as the first consumer.
• Keep Claude and Codex implementations provider-specific internally, but expose similar inputs where practical.

Non-Goals

• Do not centralize repo-specific workflows unless they are reused across multiple repos.
• Do not require consumers to use a submodule for basic workflow reuse.
• Do not hide required permissions behind broad defaults.
• Do not preserve legacy duplicated workflows after migration.
• Do not build a general SaaS review platform.

Proposed Design

Create a shared repo, for example:

• vx/github-actions
• vx/shared-actions
• vx/gha-common

Recommended layout:

.github/workflows/
  claude-pr-review.yml
  claude-mention-assistant.yml
  codex-pr-review.yml
  nix-flake-check.yml        # optional later
  update-flake-lock.yml      # optional later

claude/
  agent/action.yml
  pr-review/action.yml

codex/
  pr-review/action.yml

docs/
  security.md
  consumers.md
  migration.md

README.md

The public consumer interface should be reusable workflows. Composite actions should be used inside the shared repo to avoid repeating implementation details.

This mirrors:

• WalletConnect/actions: composite actions for Claude-specific automation.
• oxidian/actions: reusable workflow wrapping a Codex review action.

Initial Workflows

Claude PR Review

Reusable workflow:

.github/workflows/claude-pr-review.yml

Responsibilities:

• Run on caller-defined PR triggers.
• Checkout the repo.
• Invoke anthropics/claude-code-action.
• Use a standard review prompt.
• Support optional repo-specific context.
• Support a narrow default allowed-tool list.
• Support progress tracking.

Example consumer workflow:

name: Claude PR Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  claude-review:
    uses: vx/github-actions/.github/workflows/claude-pr-review.yml@v1
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    secrets:
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    with:
      model: claude-opus-4-7
      track-progress: true

Claude Mention Assistant

Reusable workflow:

.github/workflows/claude-mention-assistant.yml

Responsibilities:

• Support issue comments, PR review comments, PR reviews, and new issues.
• Trigger only when @claude appears in relevant content.
• Pass actions: read only when the caller grants it.
• Allow caller-provided project context and allowed tools.

Example consumer workflow:

name: Claude Mention Assistant

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  pull_request_review:
    types: [submitted]
  issues:
    types: [opened]

jobs:
  claude-mention-assistant:
    uses: vx/github-actions/.github/workflows/claude-mention-assistant.yml@v1
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    secrets:
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    with:
      model: claude-opus-4-7
      trigger-phrase: '@claude'

Codex PR Review

Reusable workflow:

.github/workflows/codex-pr-review.yml

Responsibilities:

• Wrap openai/codex-action.
• Support PR-triggered and comment-triggered review.
• Optionally wait for CI before reviewing.
• Emit structured review output where possible.
• Post a sticky PR comment or expose output for caller-controlled posting.
• Use safe Codex defaults.

Example consumer workflow:

name: Codex PR Review

on:
  pull_request:
    types: [opened, ready_for_review, synchronize]
  issue_comment:
    types: [created]

jobs:
  review:
    uses: vx/github-actions/.github/workflows/codex-pr-review.yml@v1
    permissions:
      contents: read
      pull-requests: write
      issues: write
      checks: read
    secrets:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    with:
      model: gpt-5.5
      effort: xhigh
      safety-strategy: drop-sudo

Inputs

Initial shared Claude inputs:

• model
• track-progress
• trigger-phrase
• extra-prompt
• project-context
• allowed-tools
• checkout-fetch-depth

Initial shared Codex inputs:

• model
• effort
• responses-api-endpoint
• safety-strategy
• review-trigger-phrase
• ci-timeout-minutes
• extra-prompt
• project-context

Required secrets:

• CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY
• OPENAI_API_KEY

Security Requirements

• Use least-privilege permissions in caller workflows.
• Prefer explicit secret mapping over secrets: inherit.
• Pin third-party actions intentionally and update them centrally.
• Document why each permission is required.
• Keep Claude allowed tools narrow by default.
• Avoid broad allowed_bots values, especially '*'.
• Do not allow non-write users to trigger write-capable workflows by default.
• Avoid pull_request_target unless there is a specific reviewed design for it.
• For Codex, default to safety-strategy: drop-sudo or unprivileged-user; do not default to unsafe.
• Never hardcode Anthropic, Claude OAuth, OpenAI, or Azure OpenAI credentials in workflow files.
• Add workflow linting, ideally with actionlint.

Migration Plan

1. Create the shared GitHub Actions repo.
2. Add Claude composite actions for mention assistant and PR review.
3. Add reusable Claude workflows that call those composite actions.
4. Add Codex PR review composite action and reusable workflow.
5. Add docs for consumers, permissions, secrets, and security assumptions.
6. Tag the first stable release as v1.
7. Migrate this repo as the first consumer.
8. Remove duplicated Claude workflow bodies from this repo.
9. Evaluate whether Nix workflows should be added next.

Acceptance Criteria

• Shared repo exists and is documented.
• claude-pr-review.yml is available as a reusable workflow.
• claude-mention-assistant.yml is available as a reusable workflow.
• codex-pr-review.yml is available as a reusable workflow or explicitly deferred.
• Required secrets, permissions, and inputs are documented.
• At least one repo consumes the shared workflows through jobs.<job>.uses.
• Duplicated Claude workflow logic is removed from the migrated repo.
• Shared workflows are tagged with a stable version.
• Security defaults are documented and conservative.
• Failure behavior and required setup are documented.

Open Questions

• What should the shared repo be named?
• Should the repo be public or private?
• Should consumers pin to @v1 or full commit SHA?
• Should Codex support be included in v1, or added immediately after Claude migration?
• Should repo-specific prompts live in caller workflow inputs, checked-in prompt files, or both?
• Should shared shell scripts live in this repo later, or remain repo-local until reused?