review.yml

name: Kyosei Review

on:
  workflow_call:
    # At least one secret is required.
    # Typically only one is needed.
    # If multiple are provided they are passed through to claude-code-action as-is.
    secrets:
      claude_code_oauth_token:
        description: Claude Code OAuth token
        required: false
      anthropic_api_key:
        description: Anthropic API key (alternative to OAuth token)
        required: false
      custom_github_token:
        description: >-
          GitHub token for API access.
          If omitted, claude-code-action uses Claude GitHub App token (claude[bot]).
          Provide explicitly to use a custom token or github.token instead.
        required: false

    inputs:
      # Authentication
      use_bedrock:
        description: Use Amazon Bedrock with OIDC authentication
        type: boolean
        required: false
        default: false
      use_vertex:
        description: Use Google Vertex AI with OIDC authentication
        type: boolean
        required: false
        default: false
      use_foundry:
        description: Use Microsoft Foundry with OIDC authentication
        type: boolean
        required: false
        default: false

      # Claude Code Action pass-through
      allowed_bots:
        description: >-
          Comma-separated list of allowed bot usernames, or '*' to allow all bots.
          Defaults to '*' because bots are not inherently more dangerous than humans.
        type: string
        required: false
        default: "*"
      allowed_non_write_users:
        description: >-
          Comma-separated list of users without write permission who are allowed to trigger Claude,
          or '*' to allow all. Only works when custom_github_token is provided.
          Enables bubblewrap sandbox and env scrubbing for safety.
        type: string
        required: false
        default: ""
      include_comments_by_actor:
        description: >-
          Filter to include only comments from specific actors.
          Supports wildcards (e.g. '*[bot]'). Empty means include all.
        type: string
        required: false
        default: ""
      exclude_comments_by_actor:
        description: >-
          Filter to exclude comments from specific actors.
          Supports wildcards. Exclusion takes precedence over inclusion.
        type: string
        required: false
        default: ""
      additional_permissions:
        description: >-
          Additional GitHub permissions for the App token (newline-separated 'key: value').
          Example: 'actions: read' enables CI/CD failure analysis.
          Only effective with OIDC token exchange (ignored when custom_github_token is set).
        type: string
        required: false
        default: ""
      settings:
        description: >-
          Claude Code settings as a JSON object, or a path to a file containing one.
          The job fails when it is neither, because the value is parsed here
          to merge it with the `permissions.additionalDirectories` built from
          the `additional_directories` input.
          Also merged with existing settings (input takes precedence).
          Can configure hooks, env, MCP settings, etc.
        type: string
        required: false
        default: ""

      # Claude Code configuration
      model:
        description: Claude model to use
        type: string
        required: false
        default: "opus"
      effort:
        description: >-
          Reasoning effort level for the top-level orchestrator session
          (low, medium, high, xhigh, max).
          The kyosei skill itself only dispatches reviewer subagents and posts JSON,
          so a lower level reduces cost and latency without affecting review quality.
          Reviewer subagents declare their own effort in agent frontmatter,
          which overrides this session-level value per Claude Code's agent fields spec.
          Set to an empty string to omit the flag and use the model default.
        type: string
        required: false
        default: "low"
      allowed_tools:
        description: >-
          Allowed tools for Claude Code (newline-separated, replaces the default set below).
          The default allows `Bash` without any command restriction and `Write`,
          because the kyosei plugin runs its own bundled binaries
          whose names and paths differ per release,
          reviewers write intermediate results to scratch files,
          and `node` alone already permits arbitrary code execution anyway.
          Reviewer subagents restrict their own tools in agent frontmatter,
          but that is not a boundary because general-purpose subagents
          inherit the tools of the session that started them.
          The disposable runner only protects the working tree:
          the session can read the credentials in the process environment
          and has ways to send them elsewhere.
          Since the pull request text it reads is attacker controlled,
          replace this default with a stricter policy
          when you review untrusted input such as fork pull requests.
          See the README for details.
          List each GitHub MCP tool individually as `mcp__github__<tool_name>`,
          because claude-code-action only starts the GitHub MCP server
          when a tool name begins with `mcp__github__`
          (the bare `mcp__github` prefix does not work).
          The default also allows what the bundled plugins need:
          the `Agent` tool and the MCP servers used by the research survey agent
          (`mcp__backlog__*`, `mcp__plugin_nix-tasuke_nixos`, `mcp__plugin_research_*`).
          The `mcp__plugin_*` servers ship with the bundled plugins and work out of the box.
          Backlog (`mcp__backlog__*`) is not bundled, so it only works
          if you configure the Backlog MCP server yourself (for example via `.mcp.json`).
        type: string
        required: false
        default: |
          Agent
          Bash
          Glob
          Grep
          Read
          Skill
          Task
          TodoWrite
          WebFetch
          WebSearch
          Write
          mcp__backlog__get_issue
          mcp__backlog__get_issue_comments
          mcp__backlog__get_issues
          mcp__backlog__get_myself
          mcp__backlog__get_notifications
          mcp__backlog__get_project
          mcp__backlog__get_project_list
          mcp__backlog__get_pull_request
          mcp__backlog__get_pull_requests
          mcp__backlog__get_wiki
          mcp__backlog__get_wiki_pages
          mcp__github__get_code_scanning_alert
          mcp__github__get_commit
          mcp__github__get_dependabot_alert
          mcp__github__get_discussion
          mcp__github__get_discussion_comments
          mcp__github__get_file_contents
          mcp__github__get_issue
          mcp__github__get_issue_comments
          mcp__github__get_job_logs
          mcp__github__get_label
          mcp__github__get_latest_release
          mcp__github__get_me
          mcp__github__get_pull_request
          mcp__github__get_pull_request_diff
          mcp__github__get_pull_request_files
          mcp__github__get_pull_request_review_comments
          mcp__github__get_pull_request_reviews
          mcp__github__get_pull_request_status
          mcp__github__get_release_by_tag
          mcp__github__get_secret_scanning_alert
          mcp__github__get_tag
          mcp__github__get_team_members
          mcp__github__get_teams
          mcp__github__get_workflow_run
          mcp__github__issue_read
          mcp__github__list_branches
          mcp__github__list_code_scanning_alerts
          mcp__github__list_commits
          mcp__github__list_dependabot_alerts
          mcp__github__list_discussion_categories
          mcp__github__list_discussions
          mcp__github__list_issue_types
          mcp__github__list_issues
          mcp__github__list_pull_requests
          mcp__github__list_releases
          mcp__github__list_secret_scanning_alerts
          mcp__github__list_sub_issues
          mcp__github__list_tags
          mcp__github__list_workflow_jobs
          mcp__github__list_workflow_runs
          mcp__github__list_workflows
          mcp__github__pull_request_read
          mcp__github__search_code
          mcp__github__search_issues
          mcp__github__search_pull_requests
          mcp__github__search_repositories
          mcp__github__search_users
          mcp__plugin_nix-tasuke_nixos
          mcp__plugin_research_cloudflare
          mcp__plugin_research_context7
          mcp__plugin_research_deepwiki
          mcp__plugin_research_mdn
          mcp__plugin_research_microsoft-learn
      additional_allowed_tools:
        description: Additional allowed tools to append to allowed_tools (newline-separated)
        type: string
        required: false
        default: ""
      additional_directories:
        description: >-
          Extra directories Claude may read and write outside the workspace
          (newline-separated absolute paths).
          These are appended to the built-in ones,
          which are `$RUNNER_TEMP`, `$XDG_RUNTIME_DIR` and `$TMPDIR` (or `/tmp`)
          when they exist and are writable.
          The kyosei skill writes review information files under those directories,
          and Claude Code puts its own scratch files there,
          so tools would otherwise be denied for being outside the workspace.
          The action merges this list into the settings it passes to claude-code-action
          as `permissions.additionalDirectories`,
          together with whatever the `settings` input already contains.
        type: string
        required: false
        default: ""
      claude_args:
        description: >-
          Additional arguments to pass to Claude CLI
          (appended after --model and --allowed-tools)
        type: string
        required: false
        default: ""

      # UI control
      include_fix_links:
        description: Include 'Fix this' deep links in PR review feedback
        type: boolean
        required: false
        default: true
      display_report:
        description: >-
          Display Claude Code Report in GitHub Step Summary.
          Useful for understanding what Claude did during the review.
          "auto" (default) enables it only for private repositories.
          "always" enables it regardless of repository visibility.
          "never" disables it entirely.
          "true"/"false" are accepted as aliases for backward compatibility.
        type: string
        required: false
        default: "auto"
      show_full_output:
        description: >-
          Show full Claude Code JSON output in Actions logs.
          May contain secrets in tool results; use only for debugging.
          Ignored on public repositories to prevent secret leakage.
        type: boolean
        required: false
        default: false

      # Marketplace and plugin
      marketplace_url:
        description: Git URL of the plugin marketplace
        type: string
        required: false
        default: "https://github.com/ncaq/konoka.git"
      plugin_name:
        description: Plugin identifier within the marketplace (newline-separated for multiple)
        type: string
        required: false
        default: |-
          kyosei@konoka
          nix-tasuke@konoka
          research@konoka

      # Self-hosted runner support
      self_hosted_packages:
        description: >-
          Newline-separated list of packages to install via apt-get on self-hosted runners.
          Installation runs only when the runner is self-hosted and apt-get is available.
          Set to an empty string to skip installation entirely.
        type: string
        required: false
        default: |
          curl
          gawk
          gh
          git
          jq
          zstd

      # Workflow configuration
      runs-on:
        description: >-
          Runner label(s) for the job.
          A single label can be written as a plain string
          (e.g. ubuntu-24.04)
          or a JSON string
          (e.g. "ubuntu-24.04").
          Multiple labels require a JSON array
          (e.g. ["self-hosted", "linux"]).
          An object with group/labels keys
          (e.g. {"group":"my-group","labels":["x64"]})
          is also accepted.
        type: string
        required: false
        default: ubuntu-24.04
      timeout-minutes:
        description: Job timeout in minutes. Set as a safeguard against hangs.
        type: number
        required: false
        default: 60
      fetch-depth:
        description: >-
          Number of commits to fetch.
          Fetches some history so git log can provide past context for reviews.
        type: number
        required: false
        default: 50

permissions: {}

# Cancel previous runs on the same PR to avoid stale reviews.
# The review agent reads the current PR state, so concurrent runs
# on different revisions would produce inconsistent results.
concurrency:
  group: kyosei-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  kyosei:
    name: review
    # Normalize runs-on input for `fromJSON()`:
    #   - JSON-quoted string (starts with `"`): pass through
    #   - JSON array (starts with `[`): pass through
    #   - JSON object (starts with `{`): pass through
    #   - Plain string: wrap in JSON quotes via `format()`
    runs-on: ${{
      fromJSON(startsWith(inputs['runs-on'], '"') &&
      inputs['runs-on'] ||
      startsWith(inputs['runs-on'], '[') &&
      inputs['runs-on'] ||
      startsWith(inputs['runs-on'], '{') &&
      inputs['runs-on'] ||
      format('"{0}"', inputs['runs-on']))
      }}
    # Claude GitHub App manages its own token, so only minimal permissions are needed.
    # If the caller passes `custom_github_token` explicitly, additional permissions
    # (e.g. `pull-requests: write`)
    # must be granted by the caller.
    permissions:
      contents: read # Read repository contents for checkout
      id-token: write # Required for Claude Code Action OIDC authentication
    timeout-minutes: ${{ inputs['timeout-minutes'] }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
          fetch-depth: ${{ inputs['fetch-depth'] }}
      - uses: ncaq/kyosei-action@v2.4.0 # zizmor: ignore[unpinned-uses] self-reference
        with:
          claude_code_oauth_token: ${{ secrets.claude_code_oauth_token }}
          anthropic_api_key: ${{ secrets.anthropic_api_key }}
          use_bedrock: ${{ inputs.use_bedrock && 'true' || 'false' }}
          use_vertex: ${{ inputs.use_vertex && 'true' || 'false' }}
          use_foundry: ${{ inputs.use_foundry && 'true' || 'false' }}
          custom_github_token: ${{ secrets.custom_github_token }}
          allowed_bots: ${{ inputs.allowed_bots }}
          allowed_non_write_users: ${{ inputs.allowed_non_write_users }}
          include_comments_by_actor: ${{ inputs.include_comments_by_actor }}
          exclude_comments_by_actor: ${{ inputs.exclude_comments_by_actor }}
          additional_permissions: ${{ inputs.additional_permissions }}
          settings: ${{ inputs.settings }}
          model: ${{ inputs.model }}
          effort: ${{ inputs.effort }}
          allowed_tools: ${{ inputs.allowed_tools }}
          additional_allowed_tools: ${{ inputs.additional_allowed_tools }}
          additional_directories: ${{ inputs.additional_directories }}
          claude_args: ${{ inputs.claude_args }}
          include_fix_links: ${{ inputs.include_fix_links && 'true' || 'false' }}
          display_report: ${{ inputs.display_report }}
          show_full_output: ${{ inputs.show_full_output && 'true' || 'false' }}
          marketplace_url: ${{ inputs.marketplace_url }}
          plugin_name: ${{ inputs.plugin_name }}
          self_hosted_packages: ${{ inputs.self_hosted_packages }}