charles/claude-hooks

Fork

You've already forked claude-hooks

Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

MF-1: GitHub adapter for ForgePort #292

New issue

Closed

opened 2026-04-23 23:33:10 +00:00 by code-lead · 0 comments

code-lead commented

2026-04-23 23:33:10 +00:00

Collaborator

Copy link

As a platform engineer, I want a GitHub implementation of ForgePort so that a GitHub-hosted repo routes through the exact same domain code paths as Forgejo, with no adapter-awareness leaking into the agent runner.

Acceptance criteria

Adapter surface

New apps/server/src/infrastructure/forge/github-adapter.ts implementing every method on ForgePort (see forgejo-port.ts).
Auth via per-agent GitHub PAT (Personal Access Token), loaded through the same token_file scheme the Forgejo adapter uses today. GitHub App installation tokens are deferred (see Out of scope).
All error cases return null / false per the ForgePort contract — no throwing across the hex boundary.

Issues & labels

getIssue / listIssues: REST GET /repos/{owner}/{repo}/issues[?...]. Filters: labels, milestone (by title → id lookup), state, limit (per_page).
addLabels / removeLabel: REST /issues/{n}/labels. No numeric-id dance — GitHub accepts names.

Pull requests & reviews

getPullRequest / listPullRequests: REST /pulls, baseRef filter via base= query.
requestReview / removeReviewRequest / listReviews: REST /pulls/{n}/requested_reviewers + /reviews.

Dependencies (divergence)

GitHub has no native issue-dependency API. getBlockers / getBlocked parse the issue body for Depends on #n / Blocks #n lines (the existing fallback path in deps.ts).
addBlocker appends the line to the body.
Document the divergence in the adapter header so operators know dependency ordering is body-text on GitHub, native on Forgejo.

CI / workflow status

getAggregateStatus / listWorkflowRuns / getJobLogs: REST /commits/{sha}/check-runs + /actions/runs + /actions/jobs/{jobId}/logs.
repoHasWorkflows: HEAD /contents/.github/workflows.

Files & repo scope

writeFile: REST PUT /contents/{path} with base64 body + sha.
listAccessibleRepos: /user/repos?affiliation=owner,collaborator.

Rate-limit handling

On X-RateLimit-Remaining: 0, wait until X-RateLimit-Reset (bounded retry, max 1 attempt) before surfacing the error.

Tests

The cross-adapter conformance suite (MF-6) runs against the GitHub adapter using recorded fixtures (not live API).
Rate-limit path has a fixture scenario.

Out of scope

GitHub App authentication (installation tokens). Defer to a follow-up; only block if PAT hits secondary rate limits in production.
GraphQL surface — REST is sufficient for the full ForgePort contract.
Mirroring webhooks from GitHub into the claude-hooks webhook endpoint — that is MF-3.

References

Spec: specs/multi-forge.md § MF-1.
apps/server/src/infrastructure/forge/forgejo-port.ts — port surface to preserve.
apps/server/src/infrastructure/forge/forgejo-adapter.ts — reference adapter.
apps/server/src/domain/workflow/deps.ts — existing body-text parser used as fallback.

Dependencies

Blocks on MF-4 (config schema + adapter factory). The factory decides which adapter class to instantiate per repo, so MF-4 must land before this adapter can be wired into webhook-config / agent-runner.
Delivered paired with MF-6 (conformance suite) — the harness emerges from this adapter's test scaffolding, not before.

Depends on #295 (MF-4)

As a platform engineer, I want a GitHub implementation of `ForgePort` so that a GitHub-hosted repo routes through the exact same domain code paths as Forgejo, with no adapter-awareness leaking into the agent runner. ## Acceptance criteria ### Adapter surface - [ ] New `apps/server/src/infrastructure/forge/github-adapter.ts` implementing every method on `ForgePort` (see `forgejo-port.ts`). - [ ] Auth via per-agent GitHub PAT (Personal Access Token), loaded through the same `token_file` scheme the Forgejo adapter uses today. GitHub App installation tokens are deferred (see Out of scope). - [ ] All error cases return `null` / `false` per the `ForgePort` contract — no throwing across the hex boundary. ### Issues & labels - [ ] `getIssue` / `listIssues`: REST `GET /repos/{owner}/{repo}/issues[?...]`. Filters: `labels`, `milestone` (by title → id lookup), `state`, `limit` (`per_page`). - [ ] `addLabels` / `removeLabel`: REST `/issues/{n}/labels`. No numeric-id dance — GitHub accepts names. ### Pull requests & reviews - [ ] `getPullRequest` / `listPullRequests`: REST `/pulls`, `baseRef` filter via `base=` query. - [ ] `requestReview` / `removeReviewRequest` / `listReviews`: REST `/pulls/{n}/requested_reviewers` + `/reviews`. ### Dependencies (divergence) - [ ] GitHub has no native issue-dependency API. `getBlockers` / `getBlocked` parse the issue body for `Depends on #n` / `Blocks #n` lines (the existing fallback path in `deps.ts`). - [ ] `addBlocker` appends the line to the body. - [ ] Document the divergence in the adapter header so operators know dependency ordering is body-text on GitHub, native on Forgejo. ### CI / workflow status - [ ] `getAggregateStatus` / `listWorkflowRuns` / `getJobLogs`: REST `/commits/{sha}/check-runs` + `/actions/runs` + `/actions/jobs/{jobId}/logs`. - [ ] `repoHasWorkflows`: HEAD `/contents/.github/workflows`. ### Files & repo scope - [ ] `writeFile`: REST `PUT /contents/{path}` with base64 body + sha. - [ ] `listAccessibleRepos`: `/user/repos?affiliation=owner,collaborator`. ### Rate-limit handling - [ ] On `X-RateLimit-Remaining: 0`, wait until `X-RateLimit-Reset` (bounded retry, max 1 attempt) before surfacing the error. ### Tests - [ ] The cross-adapter conformance suite (MF-6) runs against the GitHub adapter using recorded fixtures (not live API). - [ ] Rate-limit path has a fixture scenario. ## Out of scope - GitHub App authentication (installation tokens). Defer to a follow-up; only block if PAT hits secondary rate limits in production. - GraphQL surface — REST is sufficient for the full `ForgePort` contract. - Mirroring webhooks from GitHub into the claude-hooks webhook endpoint — that is MF-3. ## References - Spec: [`specs/multi-forge.md`](../src/branch/main/specs/multi-forge.md) § MF-1. - `apps/server/src/infrastructure/forge/forgejo-port.ts` — port surface to preserve. - `apps/server/src/infrastructure/forge/forgejo-adapter.ts` — reference adapter. - `apps/server/src/domain/workflow/deps.ts` — existing body-text parser used as fallback. ## Dependencies - **Blocks on MF-4** (config schema + adapter factory). The factory decides which adapter class to instantiate per repo, so MF-4 must land before this adapter can be wired into `webhook-config` / `agent-runner`. - Delivered **paired with MF-6** (conformance suite) — the harness emerges from this adapter's test scaffolding, not before.  - Depends on #295 (MF-4)

code-lead added the

area:infra

area:security

type:user-story

labels

2026-04-23 23:33:10 +00:00

dev was assigned by code-lead

2026-04-23 23:33:10 +00:00

code-lead referenced this issue

2026-04-23 23:34:18 +00:00

MF-5: Forge-neutral MCP namespace (mcp__forge__*) #296

code-lead referenced this issue

2026-04-23 23:34:18 +00:00

MF-6: Cross-adapter ForgePort conformance suite #297

code-lead referenced this issue

2026-04-23 23:34:18 +00:00

MF-9: Multi-forge runbook + docs #300

code-lead referenced this issue

2026-04-23 23:34:47 +00:00

Tracking: multi-forge spec breakdown (Forgejo + GitHub + GitLab behind ForgePort) #291

dev referenced this issue from a pull request that will close it,

2026-04-23 23:42:35 +00:00

feat(forge): GitHub adapter for ForgePort (MF-1) #303

charles referenced this issue from a commit

2026-04-24 08:13:55 +00:00

feat(forge): per-repo forge binding + adapter factory (MF-4)

claude-desktop referenced this issue

2026-04-24 08:14:26 +00:00

feat(forge): per-repo forge binding + adapter factory (MF-4) #309

code-lead closed this issue

2026-04-24 09:11:36 +00:00

No Branch/Tag specified

main

chore/sync-pre-push-from-forge-base

fix/flows-yaml-dispatch-identity

feat/board-tap-to-assign

dev/1107

code-lead/1106

code-lead/1108

dev/1104

code-lead/1103

code-lead/1080

dev/1087

feat/flows-yaml-ci-events

chore/board-drop-stalled-and-density-controls

fix/flows-yaml-routes-always-register

flows-yaml/api-defaults

dev/1023

fix/event-log-history-bleed

fix/janitor-fix-ci-logs-and-cap

dev/1022

fix/board-card-provider

code-lead/1036

dev/1025

code-lead/1020

dev/1017

code-lead/1026

feat/web-shortcut-registry-1018

dev/1015

code-lead/1009

code-lead/1008

dev/975

dev/969

dev/973

dev/967

code-lead/968

code-lead/953

dev/970

dev/976

code-lead/966

code-lead/956

code-lead/951

dev/962

dev/963

dev/977

dev/955

dev/983

dev/961

dev/974

code-lead/950

code-lead/939

dev/941

dev/940

dev/937

dev/938

dev/936

dev/935

feat/web-i18n-fr-locale

feat/spec-editor-ui-polish

chore/drop-legacy-compat

fix/skills-drop-preview-pane

fix/882-skills-safety-rail

dev/911

dev/909

dev/923

dev/917

dev/915

feat/879-sr11-m2-drop-legacy-skill

code-lead/873

dev/881

code-lead/869

dev/867

code-lead/845

code-lead/843

code-lead/844

dev/837

dev/861

dev/849

code-lead/837

code-lead/842

fix/dedup-rebase-inflight

dev/838

code-lead/847

dev/833

code-lead/848

pr/838

code-lead/841

feat/settings-save-bar/836

code-lead/840

dev/846

code-lead/839

dev/832

fix/board-sse-stale-cache

dev/834

dev/835

feat/settings-breadcrumbs

feat/forge-oauth-credentials

refactor/service-config-consolidation

feat/agent-tokens-to-secrets

feat/gitlab-oauth-to-db

feat/authelia-rip-and-voice-fixes

fix/rebase-storm-and-dead-letter

code-lead/797

code-lead/796

dev/811

code-lead/798

dev/810

code-lead/795

dev/808

code-lead/794

dev/805

dev/802

dev/803

feat/avatar-menu-settings-entry

feat/per-agent-token-tracking

dev/793

dev/747

dev/752

code-lead/790

code-lead/759

dev/756

dev/760

dev/741

dev/767

dev/740

dev/709

dev/644

dev/637

boss/614

dev/600

dev/611

dev/585

fix/login-bonus-fixes

boss/544

dev/542

refactor/api-prefix-and-session-gate

dev/489

boss/531

boss/518

dev/499

boss/516

dev/530

dev/517

dev/519

dev/515

dev/522

dev/503

dev/471

boss/329

dev/417

dev/418

dev/402

boss/327

dev/334

dev/332

boss/326

boss/325

dev/331

boss/324

boss/323

boss/322

dev/294

test/s11-task-analytics

dev/262

boss/270

dev/268

foreman/ui-consolidation-spec

dev/234

boss/196

boss/176

boss/164

fix/124-session-persist-bind

boss/52

dev/87

boss/73

dev/77

dev/81

dev/82

boss/79

dev/42

dev/35

boss/7

No results found.

Labels

Clear labels

area:agents

Agent types, pool scheduling, per-instance config

area:dashboard

Dashboard UI and observability surfaces

area:database

DB layer — schema, migrations, ORM, raw SQL

area:design

UI/UX mockup work — routes to designer agent

area:design-review

Design review dispatch — routes to design-reviewer agent

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

area:infra

Deployment, isolation, containers, systemd units

area:meta

Tracking, scaffolding, project setup

area:security

Security — routes to reviewer-security (opus)

area:sessions

Session-id store, Claude SDK resume logic

area:webhook

Forgejo webhook routing and handlers

area:workdir

Clone cache, worktrees, git identity

security

Security-sensitive issue

Tracking or decisions, not implementation work

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

dev

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#292

Reference in a new issue

Repository

charles/claude-hooks

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns