feat: add GitHub integration to run Kit as a collaborator/reviewer

[ezynda3]

Feature Description

Add a first-class GitHub integration that lets users set up Kit as an automated collaborator/reviewer in their GitHub repositories. Users could mention Kit in issue/PR comments (e.g. /kit fix this bug, /kit review) or have Kit automatically review pull requests and triage issues. Kit would run inside a GitHub Actions runner, read the relevant context (issue thread or PR diff), run the agent non-interactively, and respond by posting comments, pushing branches, and opening PRs.

Concretely, this would consist of three pieces:

1. A composite GitHub Action (e.g. mark3labs/kit-action@v1) that installs the Kit binary, checks out the repo, and runs Kit in --quiet mode against the comment/PR context.
2. A kit github install command — an interactive setup that prompts for provider/model and auto-writes .github/workflows/kit.yml.
3. A GitHub handler that reads context, enforces permissions, posts comments/reactions, and creates branches/PRs.

This is directly inspired by how opencode implements its GitHub agent.

Motivation / Use Case

Kit already supports a non-interactive subprocess mode (kit --quiet --no-session --no-extensions --system-prompt ... --model ... "prompt"), which maps almost perfectly onto the "run an agent inside a CI runner" model. Today, however, there is no turnkey way to wire Kit into a GitHub repo as a reviewer/collaborator — users would have to hand-roll workflow YAML, auth, context extraction, and comment posting themselves.

A built-in integration would let teams:

• Trigger Kit on demand from a comment (/kit ...) to fix bugs, answer questions, or implement small changes that land as a PR.
• Get automatic PR reviews on pull_request events (code quality, bugs, suggestions).
• Run scheduled issue triage (e.g. weekly cron to label/triage or surface TODOs).

This turns Kit from a local TUI tool into a collaborator that participates in the team's GitHub workflow, dramatically widening where Kit provides value.

Proposed Implementation

Based on research into how opencode structures this, with a recommendation to start simpler (no hosted backend required):

Phase 1 — Action + install command using GITHUB_TOKEN (no hosted infra):

Rather than opencode's GitHub App + OIDC token-exchange backend (which requires running a hosted service at api.opencode.ai), Kit can start with the built-in secrets.GITHUB_TOKEN for git/PR operations plus a user-provided provider secret (e.g. ANTHROPIC_API_KEY). This captures ~90% of the value with zero hosted infrastructure.

A generated .github/workflows/kit.yml:

name: kit
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  kit:
    if: |
      startsWith(github.event.comment.body, '/kit') ||
      contains(github.event.comment.body, ' /kit')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: mark3labs/kit-action@v1
        with:
          model: anthropic/claude-sonnet-4
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

A new kit github install command (interactive prompt for provider/model) that:

• Writes the workflow file above.
• Optionally uses the gh CLI, if available, to set the provider secret automatically (an improvement over opencode, which requires manual secret setup).
• Prints next steps.

Phase 2 — GitHub handler logic (could be implemented as a Kit extension, fitting the extension-first architecture):

• Detect trigger mode: comment-triggered vs pull_request auto-review vs scheduled.
• Read context (full issue thread, or PR diff via the GitHub API / gh).
• React with 👀 on the trigger comment while processing.
• Run the agent; if it leaves uncommitted changes, summarize them, push a kit-agent[bot] branch, and open a PR.
• Post the response as a comment; remove the reaction when done.

Security parity to copy from opencode regardless of approach:

• Gate triggers on write/admin collaborator permission only.
• Use persist-credentials: false; use short-lived, repo-scoped tokens.
• Run only inside ephemeral Actions runners; commit as a dedicated kit-agent[bot] identity.

Phase 3 (optional, later) — GitHub App + OIDC for a no-secrets-in-repo UX, matching opencode's polished flow. This is the only piece that needs hosted infra (a token-exchange endpoint that verifies the Actions OIDC JWT and mints a 1-hour installation token), so it should be an opt-in upgrade rather than the starting point.

Resolved design decisions (mirroring opencode)

After checking how opencode handles these, we can largely just do what it does:

• Trigger token & default events — copy opencode exactly. opencode uses /oc and /opencode, matched both at the start of a comment and after a leading space. For Kit we use /kit:

  if: |
    startsWith(github.event.comment.body, '/kit') ||
    contains(github.event.comment.body, ' /kit')

  The auto-generated workflow enables only issue_comment and pull_request_review_comment (both types: [created]), exactly like opencode. The handler can internally support more events (issues, pull_request, schedule, workflow_dispatch) but those are left out of the generated workflow for users to opt into manually.

• Core vs. extension — lean toward a bundled extension, with one caveat. opencode implements the handler in core as a built-in CLI command (packages/opencode/src/cli/cmd/github.handler.ts). However, opencode has no extension system, so core was its only option. Kit is explicitly extension-first, so a bundled extension is the more idiomatic home and lets users customize review behavior and triggers. Either is viable; this is the one spot where copying opencode verbatim deserves a conscious decision rather than an automatic copy.

[ezynda3]

Design proposal — seeking sign-off before implementation

This is a large, multi-phase feature, and the issue itself flags the core-vs-extension split as "the one spot where copying opencode verbatim deserves a conscious decision." It also references an external composite action (mark3labs/kit-action@v1) that doesn't exist yet. Before writing code I want to lock down scope + architecture so we don't build the wrong thing. Here's the proposed plan — please sign off (or correct) the open questions at the bottom.

Proposed scope for the first PR (Phase 1 only)

Land the turnkey setup path and nothing speculative:

1. kit github install command (core CLI command, in cmd/github.go)

   • Interactive huh prompt for provider/model (reuse the existing model picker used by kit install/setup).
   • Writes .github/workflows/kit.yml (template below), creating .github/workflows/ if needed; refuses to clobber an existing file unless --force.
   • If the gh CLI is detected on PATH, offer to set the provider secret (e.g. ANTHROPIC_API_KEY) via gh secret set — otherwise print the manual step.
   • Prints next steps (commit the workflow, set the secret, comment /kit ...).
   • Flags: --model, --force, --no-secret.

2. Generated workflow — copies opencode's trigger semantics, gated to issue_comment + pull_request_review_comment (types: [created]), persist-credentials: false, least-privilege permissions, if: guard on /kit.

name: kit
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  kit:
    if: |
      startsWith(github.event.comment.body, '/kit') ||
      contains(github.event.comment.body, ' /kit')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: mark3labs/kit-action@v1
        with:
          model: anthropic/claude-sonnet-4
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Recommendation on core-vs-extension (the flagged decision)

Handler logic → bundled Kit extension; github install command → core. Rationale:

• Kit is explicitly extension-first; the handler (context extraction, 👀 reaction, comment posting, branch/PR creation, permission gating) is exactly the kind of customizable behavior users will want to fork. An extension lets teams tweak review prompts/triggers without recompiling.
• The install command is pure scaffolding (writes a file, optionally calls gh), so it belongs in core next to kit install / kit setup.
• This keeps core small and matches the architecture, while still mirroring opencode's security posture (write/admin-only triggers, short-lived repo-scoped tokens, dedicated kit-agent[bot] identity).

Suggested sequencing

• PR 1 (this issue): kit github install + generated workflow + docs. Small, reviewable, no external dependencies beyond the action reference.
• PR 2: the mark3labs/kit-action composite action (separate repo) — installs the binary, checks out, runs kit --quiet --no-session ....
• PR 3: the GitHub handler extension (context read, reactions, comment/PR posting, permission gating).
• Phase 3 (later, optional): GitHub App + OIDC token exchange (needs hosted infra) — out of scope here.

Open questions (need a maintainer call)

1. Architecture: OK to put the handler in a bundled extension and only the install command in core? Or do you want the handler in core like opencode?
2. Action repo: Does mark3labs/kit-action exist / will it? Should PR 1 pin @v1 or a commit SHA? Without it the generated workflow is non-functional, so I'd like to coordinate naming/versioning.
3. Scope of PR 1: Is shipping just the install command + workflow template + docs (deferring handler/action to follow-ups) the right first slice?

I'll hold off on writing code until these three are answered. Once signed off I can start with PR 1 immediately.

[mark-iii-labs-huly]

Connected to Huly®: KIT-61

[ezynda3]

Tracking: phased rollout

Keeping this issue open as the umbrella/epic for the GitHub integration. It will close only once the integration works end-to-end. Progress:

• Phase 1 — kit github install + generated workflow + docs (feat(cmd): add kit github install command (#60) #61)
  • kit github / kit github install command, .github/workflows/kit.yml scaffolding, secret handling via the gh CLI, security hardening (author-association gate, leading /kit command-token match, secret via stdin), README + docs.
• Phase 2a — mark3labs/kit-action@v1 composite action (separate repo)
  • Installs the Kit binary, checks out the repo, runs kit --quiet --no-session ... against the comment/PR context. The Phase 1 workflow references this action, so the generated YAML is not functional end-to-end until it exists.
• Phase 2b — GitHub handler extension
  • Trigger-mode detection (comment vs. PR auto-review vs. scheduled), context extraction (issue thread / PR diff), 👀 reaction lifecycle, comment/PR posting, branch creation, permission gating. Bundled as a Kit extension per the design decision above.
• Phase 3 (optional, later) — GitHub App + OIDC token exchange
  • No-secrets-in-repo UX. Requires hosted infra (token-exchange endpoint verifying the Actions OIDC JWT). Opt-in upgrade, not the starting point.

Note: PR #61 is Part of #60, not Fixes #60, so merging it will not auto-close this issue.