Skip to content

github-api-compatibility-matrix.md

Latest commit

 

History

History
552 lines (507 loc) · 71.7 KB

github-api-compatibility-matrix.md

File metadata and controls

552 lines (507 loc) · 71.7 KB

GitHub API Compatibility Matrix

Last updated: 2026-06-02

This matrix is a top-to-bottom guide for agents and client authors. Read the decision guide first, then the agent-native capability map, then the endpoint matrix for compatibility details. It compares the local API layer in internal/router/router.go, internal/rest, and internal/graphql against the official GitHub API surface, plus local extensions that are intentionally not part of GitHub.

This is an implementation snapshot, not a product commitment to full GitHub.com parity in every area.

Agent Decision Guide

Choose agent-git-service when the work benefits from:

  • GitHub-compatible Git, repo, issue, PR, Git Database, contents, search, release, secret, variable, or workflow APIs.
  • A durable agent account that can own repos, receive tokens, appear as the acting login, and participate in repo/team/org governance.
  • Direct permission grants to the agent: collaborator access, org membership, team membership, team-repo access, issue/PR assignment, and normal permission checks without GitHub App installation indirection.
  • Self-hosted control over data, identity, Git storage, deployment boundaries, and rate-limit policy for high-volume agent traffic.
  • Agent-native state that GitHub does not expose as first-class API concepts: human-agent binding, switch sessions, wiki memory, issue presence, read receipts, attachments, connected login, and analytics.

Choose GitHub.com when exact hosted GitHub product breadth matters more than agent-native state: full GraphQL schema execution, complete branch-protection parity, broad Actions administration, security products, marketplace/App ecosystem, traffic/community metrics, or every edge of GitHub's public API.

Agent call order:

  1. Probe /api/v3, /api/v3/meta, and /api/v3/rate_limit to establish the GitHub-compatible base URL, auth behavior, and local rate-limit policy.
  2. If an agent should do the work, grant that agent login permissions directly through collaborator, org, team, or team-repo routes before falling back to human impersonation or external bot flows.
  3. Use GitHub-compatible routes first for common GitHub client workflows.
  4. Switch deliberately to local extension routes when the task needs agent-native behavior such as binding, switch sessions, read state, attachments, wiki memory, connected login, or analytics.
  5. Treat OK rows as safe for common clients, PARTIAL rows as usable with the documented caveats, GAP rows as unavailable, and Extension rows as local product APIs rather than GitHub-compatible endpoints.
  6. Do not assume GitHub.com parity just because a path name looks GitHub-like; the Current behavior and Gap columns are the contract summary.

Agent-Native Capability Map

Agent need Why agent-git-service is different from GitHub What to call / inspect
Identity, ownership, and governance Agents are first-class accounts (user_kind=agent) with their own login, token, and optional default repo. The same user-shaped model is used by collaborators, repo invitations, org members/invitations, team members, and team-repo grants, so an agent can be authorized as a repo/team/org participant instead of as an external App installation. POST /api/v3/agents; /repos/{owner}/{repo}/collaborators/{username}; /orgs/{org}/memberships/{username}; /orgs/{org}/teams/{team_slug}/memberships/{username}; /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}; models_auth.go, models_org.go, models_team.go, models_repo.go, repo_access.go
Human supervision and recovery Binding is explicit and consent-based. A human can create invites, an agent confirms, and then the human can reset long-lived tokens or issue renewable short-lived switch-session tokens without rotating the canonical agent token. /api/v3/agent-invites; /agent-bindings/confirm; /agent-bindings/{agent_login}/reset-token; /switch-session; /refresh-session; docs/design/agent-auth.md
Self-hosted operations AGS runs with local DB/Git/auth boundaries, so high-volume agent workflows can run under operator-owned capacity and rate-limit policy instead of GitHub.com quotas. Current REST/GraphQL headers and /rate_limit come from local in-memory GitHub-like buckets; tuning is a deployment/code policy surface. docs/architecture.md; internal/middleware/rate_limit.go; internal/ratelimit/ratelimit.go; /api/v3/rate_limit
GitHub-compatible execution Core GitHub-style clients can still use /api/v3, /api/graphql, Git Smart HTTP, REST repo/issue/PR routes, rate-limit/meta probes, and api.github.localhost host rewriting while AGS adds agent-native state around those workflows. internal/router/router.go; /api/v3; /api/v3/meta; /api/v3/rate_limit; Git Smart HTTP routes
Agent memory and live collaboration Wiki pages are API-addressable, git-backed memory/runbooks with tree, history, search, backlinks, labels, moves, reconcile, repair, and compact routes. Issue extensions add typing, presence, read receipts, unread counts, participant read state, and attachments. /repos/{owner}/{repo}/wiki/...; /issues/{id}/typing; /issues/{issue_id}/presence; /issues/{number}/read*; /attachments/{uuid}; handlers_wiki.go; service/wiki*.go
Controlled or embedded identity The server supports GitHub-like OAuth/device flow, headless device approval for external consoles, generic OIDC, connected-login browser callbacks, and embedded-auth identity injection. Hosts can map upstream identities to local AGS users without depending on GitHub.com identity. /login/*; /api/v3/oauth/device/*; /api/v3/oidc/*; /auth/connected/*; internal/oauth; internal/oidc; internal/connectedlogin; server.WithAuthenticator(...)
Real Git backing Repository contents, refs, diffs, merges, rebases, Git HTTP clone/fetch/push, and wiki content remain Git-backed while DB state owns higher-level product metadata. Agents can rely on real Git history instead of an API-only simulation. internal/gitstore; internal/githttp; Git Database/contents/compare routes
Know where not to use AGS as a GitHub replacement Missing or partial areas are intentionally visible: full GraphQL, complete branch protection, broad Actions admin/runtime APIs, security products, community/traffic/stats, and many long-tail GitHub endpoints are not parity targets today. Highest Priority Gaps, Remaining Gap Summary, all PARTIAL/GAP rows

Snapshot and Routing Context

Sources:

Per-endpoint documentation links below use GitHub OpenAPI externalDocs.url entries when available; broader area links point to the closest official GitHub REST or GraphQL docs page.

Local routing notes:

  • GitHub REST paths are exposed under /api/v3. Requests to api.github.localhost are rewritten to that prefix by registerHostMux.
  • Public repo reads use optional auth. Writes require auth through middleware.
  • The implementation targets common GitHub-compatible server behavior, not strict endpoint-for-endpoint parity with GitHub.com.
  • Analytics, connected login, presence, attachments, read receipts, agent binding, OIDC, wiki, org bootstrap, repo team sharing, and local token routes are local extensions unless explicitly noted below.
  • The API root advertises openapi_url so clients can discover the machine-readable local extension contract without source inspection.

Highest Priority Gaps

Area GitHub behavior Current behavior Gap Priority Evidence / Tests
Search breadth (docs) GitHub has repository, issue/PR, commit, code, label, topic, and user search Local implements repositories/issues/commits/code/labels/users/topics No remaining endpoint breadth gap; supported search endpoints ignore or approximate several sort/order/filter/ranking semantics High handlers_search.go, compat_search_test.go
Branch protection (docs) GitHub exposes a full branch protection tree: required status checks, contexts, PR review rules, signatures, restrictions, and branch rename Local supports monolithic GET/PUT/DELETE /branches/{branch}/protection, selected status-check/PR-review/enforce-admin/signature/restriction subresources including restrictions actor add/set/remove, and merge-policy enforcement for required reviews/checks plus bypass_pull_request_allowances.users Branch rename, signature enforcement, teams/apps bypass, full actor object shapes, and strict required checks remain unsupported or partial High handlers_branch.go, pr_merge_policy.go; TestBranchProtectionBypassAllowancesRESTContract, TestBranchProtectionSubresourceRESTContract, TestBranchProtectionRestrictionActorMutationSubresources, TestMergePR_BranchProtectionBypassUser
GraphQL completeness (docs) GitHub GraphQL is schema-backed with full introspection, typed errors, and broad query/mutation support Local GraphQL is a lightweight dispatcher with selected fields/mutations and filtered responses Unknown or unsupported operations often return empty data with HTTP 200; introspection is selective High internal/graphql/handler.go, gql_queries.go, gql_mutations.go

Issues

Endpoint Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET /repos/{owner}/{repo}/issues (docs) Returns issues and pull requests by default; supports state, labels, assignee, creator, mentioned, milestone, since, sort, direction Returns issues plus PRs; supports most listed filters, including mentioned across issue and PR title/body/comment text with GitHub-style mention-token boundaries Sort/filter semantics are simpler than GitHub for edge cases High OK/PARTIAL: TestCompat_IssueList_IncludesPullRequests, TestCompat_IssueList_MentionedIncludesPullRequests, TestCompat_IssueList_MentionedUsesMentionTokenBoundaries
GET /repos/{owner}/{repo}/issues/{number} (docs) Returns an issue; if the number is a PR, returns an issue-shaped PR Falls back to PR when issue lookup fails None for common clients High OK: existing tests
POST /repos/{owner}/{repo}/issues (docs) Create issue with title/body/labels/assignees/milestone Supported, including deprecated singular assignee Labels that fail to resolve may be logged and skipped in service layer rather than always producing GitHub-identical validation High OK/PARTIAL: TestCompat_IssueCREATE_SingularAssignee
PATCH /repos/{owner}/{repo}/issues/{number} (docs) Partial update; labels and assignees replace when provided Supported for issues and issue-shaped PR fallback Error bodies/statuses may differ for invalid labels, assignees, and state transitions High OK/PARTIAL: TestCompat_IssuePATCH_*
GET /repos/{owner}/{repo}/issues/comments (docs) Lists all issue comments in repo with pagination/since/sort/direction Supported None known for common CLI usage Medium OK: TestListRepoIssueComments
GET/PATCH/DELETE /repos/{owner}/{repo}/issues/comments/{comment_id} (get, update, delete) Get, update, delete issue comment Supported Fine-grained permissions and exact error payloads may differ Medium OK/PARTIAL: existing comment tests
PUT/DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}/pin (pin, unpin) PUT pins; DELETE unpins PUT pins; DELETE unpins None known for common clients High OK: TestIssueCommentPinEndpoints
GET /repos/{owner}/{repo}/issues/events and GET /repos/{owner}/{repo}/issues/events/{event_id} (list, get) Repo-wide issue event listing and event lookup Not routed Missing repo-wide event APIs Medium GAP
GET /repos/{owner}/{repo}/issues/{number}/events (docs) Issue event listing Supported Event types are limited to modeled issue lifecycle Medium PARTIAL
GET /repos/{owner}/{repo}/issues/{number}/timeline (docs) Timeline feed with many event/item types Supported Timeline item coverage is narrower than GitHub Medium PARTIAL
GET /repos/{owner}/{repo}/issues/{number}/assignees/{assignee} (docs) Check whether a user can be assigned Not routed Missing check endpoint Low GAP
Issue dependencies, sub-issues, parent, issue fields (dependencies, sub-issues, field values) GitHub exposes issue hierarchy/dependencies/issue-field endpoints Not routed Missing modern GitHub issue planning APIs Low GAP
Reactions on issues and issue comments (issues, comments) List/create/delete reactions, with media-type semantics on GitHub Supported for issues and issue comments GraphQL reaction mutations are minimal; REST media-type previews are not enforced Low PARTIAL
Local extensions None on GitHub /presence/heartbeat, /issues/{id}/typing, /issues/{id}/attachments, /repos/{owner}/{repo}/attachments, /repositories/{repo_id}/attachments, /issues/{number}/read*, /issues/{issue_id}/presence, /users/{user_id}/last-seen, /user/presence/privacy Additive local product APIs, not GitHub-compatible endpoints N/A Extension

Pull Requests

Endpoint Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET /repos/{owner}/{repo}/pulls (docs) List PRs by state, head, base, sort, direction Supported for state/head/base/sort/direction popularity and long-running sort are approximated by created timestamp High OK/PARTIAL: TestPRHandlers_ListPRs_BaseHeadFilters
GET /repos/{owner}/{repo}/pulls/{number} (docs) Full PR object; supports diff media type Supported; Accept: diff supported Exact mergeability/check fields are local approximations High OK/PARTIAL: TestCompat_PRGet_*
POST /repos/{owner}/{repo}/pulls (docs) Create PR with draft and cross-repo head support Supported Permission and validation errors do not exactly match GitHub High OK/PARTIAL: existing tests
PATCH /repos/{owner}/{repo}/pulls/{number} (docs) Partial update Supported Some fields remain unmodeled High OK: existing tests
PUT /repos/{owner}/{repo}/pulls/{number}/update-branch (docs) Merge base into head with optional expected_head_sha Supported with merge update Rebase is GraphQL-only locally, matching REST's merge-only endpoint Medium OK: TestPRHandlers_UpdateBranch
GET/PUT /repos/{owner}/{repo}/pulls/{number}/merge (check, merge) Check merge state and merge PR Supported Merge conflict/invalid-state status mapping may differ Medium PARTIAL: TestCompat_PRMerge_ResponseShape
GET /repos/{owner}/{repo}/pulls/{number}/commits and /files (commits, files) List commits and changed files on a PR Supported Commit/file response shapes and pagination are simpler than GitHub Medium PARTIAL
GraphQL auto-merge (enable, disable) GitHub can queue or cancel auto-merge when the repository allows it; queued merge should honor branch protection and optional expectedHeadOid Local supports enablePullRequestAutoMerge and disablePullRequestAutoMerge; queued merges run asynchronously when workflow runs or commit statuses satisfy the same merge policy as manual merges Auto-merge settings are configured through REST allow_auto_merge; branch-protection bypass is configured only through REST branch protection, not GraphQL High OK/PARTIAL: TestGraphQL_EnablePullRequestAutoMerge_*, TestAutoMerge_BranchProtectionWithoutBypassKeepsPROpen, TestAutoMerge_ExpectedHeadSHAMismatchBlocksMerge
PR review lifecycle (list, create, submit, update, dismiss) List/create/submit/get/dismiss/delete reviews; update pending review via PUT Most routes exist, including PUT review update No known method mismatch for update; lifecycle edge semantics may still differ High OK/PARTIAL: TestCompat_PRReviewUpdate_UsesPut
PR review comments (repo list, PR list, create, reply, update, reactions) GitHub supports repo-wide list, per-PR list, create/reply/update/delete, and reactions Local supports per-PR list, create/reply/update/delete, single comment get Missing repo-wide GET /pulls/comments; missing review comment reactions Medium PARTIAL
Requested reviewers (docs) Add/remove/list requested reviewers and teams Supported, including no-prefix compatibility routes Team/user validation is simpler than GitHub Medium OK/PARTIAL
Draft conversion (ready, draft) GitHub REST has ready-for-review; draft conversion is GraphQL Local has REST PUT .../ready_for_review plus GraphQL ready/draft mutations REST ready endpoint is local-compatible for CLI; draft conversion remains GraphQL Low OK/PARTIAL
PR archive/codespaces (archive, codespaces) GitHub has PR archive and PR codespaces routes Not routed Missing low-priority modern endpoints Low GAP
Local extensions (GraphQL thread docs) None on GitHub REST REST resolve/unresolve review comment routes Thread resolution is a GitHub GraphQL concept; REST routes are local extensions N/A Extension

Repositories, Branches, Commits, Contents

Endpoint / Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET /repos/{owner}/{repo} (docs) Rich repo metadata shape with permissions, counts, feature flags, security fields Supported with computed stats, merge defaults, local feature flags, and disabled security/code-security analysis status fields for admin viewers Optional fields for security products are status-only; exact GitHub Enterprise feature availability and admin-only visibility semantics are approximated High OK/PARTIAL: TestCompat_RepoGet_ResponseFields
PATCH /repos/{owner}/{repo} (docs) Update repo and return full repo shape Supported, including homepage, has_projects, has_downloads, has_discussions, and allow_auto_merge Some fields unmodeled; exact validation differs Medium OK/PARTIAL: TestCompat_RepoPATCH_ResponseIncludesStats, TestCompat_RepoPATCH_AllowAutoMergeRoundTrip, TestCompat_RepoPATCH_HomepageAndFeatureTogglesRoundTrip
DELETE /repos/{owner}/{repo} (docs) Delete repo Supported None known for local use Medium OK
POST /user/repos, POST /orgs/{org}/repos (user, org) Create user/org repo with many optional settings Supported for core fields plus modeled GitHub options: homepage, has_issues, has_projects, has_wiki, has_downloads, has_discussions, is_template, auto_init, license_template, merge flags, delete-branch-on-merge, and org visibility (public/private) team_id, custom_properties, .gitignore/license file materialization, and merge commit message defaults remain ignored or unmodeled; validation is simpler than GitHub High OK/PARTIAL: TestCompat_RepoCREATE_ModeledOptionsRoundTrip, TestCompat_OrgRepoCREATE_VisibilityRoundTrip
Forks and transfer (forks, create fork, transfer) Create/list forks; transfer repo Supported Async behavior and invitation workflow are simplified Medium PARTIAL
POST /repos/{owner}/{repo}/merge-upstream (docs) Sync a fork branch from upstream Supported for fast-forwarding from the fork parent when present; non-forks return a no-op success Merge conflict handling and upstream branch discovery are simplified Medium PARTIAL
GET/PUT /repos/{owner}/{repo}/topics (get, replace) Topic list/replace Supported None known Medium OK
Repository autolinks (docs) List/create/get/delete repository autolinks Supported Validation and storage are local Low OK/PARTIAL
GET /repos/{owner}/{repo}/languages (docs) Byte-count map by language Returns stored primary language with value 1 Not a real language byte analysis Low PARTIAL
GET /repos/{owner}/{repo}/branches and GET /branches/{branch} (list, get) List and fetch real branch refs Supported from Git store, fallback to default branch with zero SHA Missing protection details in branch object beyond local transform; fallback can mask git-store failures Medium PARTIAL
Branch protection tree (protection, rename) Full branch-protection REST subresource tree Monolithic /protection plus selected subresources for required status checks, contexts, enforce admins, required signatures, required PR reviews, restrictions, and restrictions actor add/set/remove for users/teams/apps Missing branch rename, signature enforcement, full actor object response shapes, and exact validation/error semantics High PARTIAL: TestBranchProtectionSubresourceRESTContract, TestBranchProtectionRestrictionActorMutationSubresources
GET /repos/{owner}/{repo}/commits (docs) Supports sha, path, author, committer, since, until, pagination Supports path and fixed git limit before pagination Most filters are missing/ignored Medium PARTIAL
GET /repos/{owner}/{repo}/commits/{ref} (commit, comments, PRs, branches) Commit details or diff Supported with file stats/patches when available Missing commit comments, branches-where-head, commit-to-PR lookup Medium PARTIAL
GET /repos/{owner}/{repo}/compare/{basehead} (docs) Compare refs; missing refs should error Supported with real git diff when possible Missing refs can return a 200 empty compare response instead of GitHub error Medium PARTIAL
GET /repos/{owner}/{repo}/contributors (docs) Contributor summary from git history with anonymous filtering options Supported from git contributor data Query options and exact aggregation differ Low PARTIAL
GET/PUT/DELETE /repos/{owner}/{repo}/contents/{path} (get, put, delete) Full contents API, links/download URLs, symlink/submodule handling, optimistic SHA concurrency File/dir read, create/update/delete with SHA validation and GitHub-style url/git_url/html_url/download_url/_links fields for common file and directory responses Symlink/submodule typing and full commit response payload details remain partial High OK/PARTIAL: ContentsSHAValidation, ContentsDirectoryListing
GET /repos/{owner}/{repo}/readme (repo root, directory) README contents object, optional ref Supported for common README names /readme/{dir} is missing; response shape is minimal Medium PARTIAL
Tags and archives (tags, zipball, tarball, git tags) GitHub has GET /tags, /zipball/{ref}, /tarball/{ref}, plus Git Database tag object APIs GET /tags, local POST /tags, release archive helpers, and Git Database tags are implemented Official /zipball/{ref} and /tarball/{ref} are missing; local POST /tags is not GitHub REST Medium PARTIAL/Extension
Collaborators, invitations, and assignees (collaborators, permission, invitations, assignees) List/check collaborators, get permission, add/remove collaborators, list invitations, list/check assignees List/add/remove collaborators, list repository invitations, and list assignees Missing GET /collaborators/{username}, /permission, and GET /assignees/{assignee} Medium GAP/PARTIAL
Deploy keys (list, create, get, delete) List/create/get/delete deploy keys List/create/delete only GET /repos/{owner}/{repo}/keys/{key_id} is missing Low GAP
Community, traffic, stats, subscribers, subscriptions, vulnerability-alert toggles (community, traffic, stats, watching, alerts) GitHub exposes many repo metadata/admin APIs Not routed Missing broad non-CLI repository surface Low GAP

Git Database

Endpoint Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET/POST /repos/{owner}/{repo}/git/blobs (get, create) Base64/UTF-8 blob create and blob fetch Supported Exact error payloads differ High OK: TestGitHandlers/GitDatabaseCreateBlobAndTree_Issue1292
GET/POST /repos/{owner}/{repo}/git/trees (get, create) Tree fetch/create with base_tree, inline content, and deletion Supported None known for core behavior High OK
GET/POST /repos/{owner}/{repo}/git/tags (get, create) Annotated tag object fetch/create; ref creation is separate Supported None known for core behavior High OK
GET/POST /repos/{owner}/{repo}/git/commits (get, create) Commit object fetch/create Supported Commit verification is local and limited High PARTIAL
GET/POST/PATCH/DELETE /repos/{owner}/{repo}/git/ref(s) (get, create, update, delete) Ref create/fetch/update/delete, including namespaced refs Supported, including singular ref compatibility Exact fast-forward and error semantics may differ High OK/PARTIAL
GET /repos/{owner}/{repo}/git/matching-refs/{ref} (docs) List matching refs Supported None known for common use Medium OK

Search

Endpoint Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET /search/repositories (docs) q required; rich qualifiers; sort/order for stars/forks/help-wanted-updated; items include score q required; many qualifiers parsed; score present; REST sort/order query params work for local star/fork/update/create/pushed sorts Help-wanted sort and some qualifier coverage remain incomplete High OK/PARTIAL: TestCompat_SearchRepos_ResponseShape, TestSearchReposStarsForksLanguageLicenseSort
GET /search/issues (docs) Searches issues and PRs with rich qualifiers/sort/order Supported with hybrid issue/PR search and many qualifiers Some qualifiers are parsed but not enforced; sort/order differs for edge cases High PARTIAL: TestCompat_SearchIssues_ResponseShape
GET /search/commits (docs) Commit search with commit-specific qualifiers; preview media type historically required Supported Preview media type not enforced; qualifier coverage is partial Medium PARTIAL
GET /search/code (docs) Code search with repo/path/language/extension/filename qualifiers and text matching Supported through git search across repos Negated qualifiers are ignored; sort/order and advanced code search semantics are missing Medium PARTIAL
GET /search/labels (docs) Search labels by q within repository_id; returns search envelope with scored label items Supported for q, repository_id, pagination, and basic created/updated sort Text-match metadata and exact ranking differ High OK/PARTIAL: TestCompat_SearchLabels_ResponseShape
GET /search/users (docs) Search users and organizations by q; supports text, type, in, count/date qualifiers, sort/order, and scored user items Supported for text, type:user/type:org, in, pagination, joined sort, and scored user items Followers/repositories/language/location/created qualifiers and exact ranking differ High OK/PARTIAL: TestCompat_SearchUsers_ResponseShape
GET /search/topics (docs) Search topics by q; returns topic items with metadata and score Supported from repository topics for text, repositories, pagination, and scored topic items Curated/featured metadata, aliases/related topics, exact ranking, and topic descriptions are repository-derived or empty High OK/PARTIAL: TestCompat_SearchTopics_ResponseShape

Releases

Endpoint Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET/POST /repos/{owner}/{repo}/releases (list, create) List/create releases Supported make_latest, discussion category, immutable releases, and exact validation are unmodeled High OK/PARTIAL: compat_release_test.go
GET /releases/latest, GET/HEAD /releases/tags/{tag} (latest, tag) Fetch latest/by tag Supported Latest semantics depend on local service ordering Medium OK/PARTIAL
GET/PATCH/DELETE /releases/{release_id} (get, update, delete) Fetch/update/delete release Supported Some fields unmodeled Medium OK/PARTIAL
POST /releases/generate-notes (docs) Generate release notes from tags/commits Supported Notes are simpler than GitHub's generated release notes Medium PARTIAL
Release assets (list, upload, get, update, delete) Upload/list/get/delete/update asset; browser download URL serves bytes Upload/list/get/delete and local /download route PATCH /releases/assets/{asset_id} is missing; browser_download_url points at API URL instead of a stable asset download URL Medium PARTIAL/GAP
Archives (zipball, tarball) GET /zipball/{ref} and /tarball/{ref} Local archive-by-tag and release archive routes Official zipball/tarball endpoints are missing Medium GAP/PARTIAL
Release reactions / immutable releases (reactions, immutable releases) Official endpoints exist Not routed Missing Low GAP

Actions, Checks, Statuses, Environments

Endpoint / Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
Workflows (list, get, dispatch) List/get/enable/disable/dispatch workflows; validate workflow_dispatch inputs/ref; list runs for a workflow Supported from repository workflow records/files; workflow_id may be numeric or filename; workflow-scoped run listing is routed Dispatch accepts payload but backend workflow engine is local/mock-oriented; validation is simpler High PARTIAL: workflow acceptance tests
Workflow runs (list, get, rerun, logs, jobs) List/get/cancel/delete/rerun/rerun-failed/force-cancel/logs/artifacts/jobs/attempts Supported subset, including run attempts, job get/logs/rerun, and force-cancel Attempts collapse to one stored attempt; job rerun/rerun-failed delegate to full-run rerun; filters and run metadata are partial High PARTIAL: compat_workflow_test.go, handlers_workflow_jobs.go
Missing Actions run APIs (workflow runs, runners, permissions, OIDC) Approvals, pending deployments, timing, delete logs, workflow timing, permissions, runners, runner groups, OIDC customization Not routed Missing broad Actions admin/runtime surface Medium GAP
Artifacts (repo list, run list, get, download, delete) List repo/run artifacts and download zip List repo/run artifacts and download zip at /actions/artifacts/{artifact_id}/zip Missing GET/DELETE /actions/artifacts/{artifact_id} metadata/delete; download path differs from official archive-format path Medium PARTIAL
Actions cache (list, delete by key, delete by id, usage) List/delete caches and usage Supported Cache usage is static; retention/storage-limit endpoints missing Low PARTIAL
Commit statuses (create, list, combined) Create/list/combined status Supported Status contexts are local; exact permissions/errors differ Medium OK/PARTIAL
Check runs/suites (runs, suites) GitHub supports create/update/rerequest check runs and suites Local maps workflow jobs/runs to read-only check runs/suites Create/update/rerequest check APIs are missing Medium GAP/PARTIAL
Deployments (deployments, statuses) Create/list deployments and create/list statuses Supported Create deployment returns 200 instead of GitHub-created/accepted status; get deployment and get single status endpoints are missing Medium PARTIAL
Environments (environments, branch policies, secrets, variables) GitHub supports list/get/create/update/delete, protection rules, deployment branch policies, env secrets/variables Local supports list/get/create-update/delete plus env secrets/variables, both by {owner}/{repo} and numeric {repo_id} compatibility routes Full parity for all protection rule flavors is still incomplete Medium PARTIAL
Repository dispatch (docs) GitHub returns 204 and can trigger workflows Returns 204 but does not fully feed a workflow engine Behavior is mostly a no-op Medium PARTIAL

Secrets and Variables

Endpoint / Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
Repo actions/dependabot/codespaces secrets (actions, dependabot, codespaces) List, public key, get secret, create/update encrypted secret, delete List/public-key/get/create-update/delete routed for repo namespaces Public key is static/local; encryption semantics differ from GitHub libsodium flow High OK/PARTIAL: TestCompat_RepoSecretGet_ByNamespace
Org actions/dependabot/codespaces secrets (actions, dependabot, codespaces) List/public-key/get/create-update/delete; set/list/add/remove selected repositories List/public-key/get/create-update/delete and bulk selected-repo set/list supported Per-repository add/remove selected endpoints are missing Medium PARTIAL
Environment secrets (docs) List/public-key/get/create-update/delete List/public-key/create-update/delete by {owner}/{repo} and numeric {repo_id} compatibility routes GET /.../secrets/{secret_name} is missing Medium PARTIAL
User codespaces secrets (docs) GitHub supports user-level codespaces secrets and selected repositories List/public-key/get/create-update/delete and selected repository routes are user-scoped Encryption semantics differ from GitHub libsodium flow; selected repo response shape is minimal High OK/PARTIAL: TestCompat_UserCodespacesSecrets
Repo/org/env variables (repo, org, environment) List/create/get/update/delete Supported; environment variables are also routed by numeric {repo_id} for gh variable set --env compatibility Org selected-repository variable endpoints are missing Medium PARTIAL
Secret scanning and private registries (secret scanning, private registries) Official GitHub security APIs exist Not routed Missing Low GAP

Organizations, Teams, Invitations

Endpoint / Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET /orgs/{org} and org repos (org, org repos, create repo) Fetch org and list/create org repos Supported PATCH/DELETE org are missing Medium PARTIAL
Org members/memberships (members, memberships, blocks) List members; get/set/delete memberships; delete member; role filters Supported subset with active/pending membership role normalization and role=admin/member/all member filtering Member check GET /orgs/{org}/members/{username}, public members, org blocks, org membership listing are missing Medium PARTIAL/GAP
Outside collaborators (docs) List and remove outside collaborators; GitHub also add/convert routes List implemented; remove via org member/collaborator flows PUT/DELETE /orgs/{org}/outside_collaborators/{username} is missing Low GAP/PARTIAL
Org invitations (pending, create, cancel, user membership) List/create/revoke org invitations; user accepts/declines Supported Invitation teams lookup and failed invitations missing Medium PARTIAL
Teams (teams, members, repos, legacy) Org team CRUD, members, invitations, repos Supported under /orgs/{org}/teams/{slug} Numeric /teams/{team_id} legacy routes and team child teams are missing Medium PARTIAL
Org audit log (docs) GitHub audit log supports rich filtering and paging Local audit log route exists Coverage and event taxonomy are local Low PARTIAL
Org rulesets (docs) GitHub supports list/create/get/update/delete/history Local only supports GET /orgs/{org}/rulesets/{ruleset_id} Org list/create/update/delete/history missing Medium GAP/PARTIAL

Users, Auth, Keys, Stars, Notifications, Gists

Endpoint / Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
GET /user, GET /users/{username} (authenticated, public) Authenticated/private user and public user shapes Supported Some optional fields absent High OK/PARTIAL: compat_user_test.go
User/org repo listing (viewer, user, org) List viewer/user/org repos with filters/sort/type Supported Query filters are mostly ignored Medium PARTIAL
User orgs (viewer, public) GET /user/orgs; public GET /users/{username}/orgs Viewer orgs supported Public user org listing missing Low GAP/PARTIAL
Stars (viewer, public) List/check/star/unstar repos; list public stars for a user Supported for current user and GET /users/{username}/starred, including anonymous reads of public starred repos and auth-aware private filtering Public per-repo star check and sort/direction variants are missing Medium PARTIAL: TestListUserStarredRepos*
SSH keys (viewer, public) User list/create/get/delete; public user keys Supported None known for common use Medium OK
SSH signing keys (viewer, public) User list/create/get/delete; public user signing keys Supported None known for common use Medium OK
GPG keys (viewer, public) List/create/delete and public user list Supported GET /user/gpg_keys/{gpg_key_id} is missing Low GAP/PARTIAL
Tokens GitHub does not expose generic /user/tokens REST endpoints Local list/create/delete token API Local extension, not GitHub API N/A Extension
Notifications (global, thread, repo) List notifications and mark all read Global GET/PUT /notifications is implemented; GET supports conditional polling via ETag/If-None-Match Thread get/patch/delete/subscription and repo notifications are missing; polling does not yet mirror GitHub's Last-Modified/X-Poll-Interval contract Medium PARTIAL
User events (docs) GitHub returns event feeds Local user event endpoints intentionally return empty arrays No event model Low PARTIAL
Gists (gists, comments) Authenticated list/create/get/update/delete Supported Public/starred/user gists, comments, commits, forks, star/unstar, and revision fetch are missing Medium PARTIAL/GAP
GitHub App installations (docs) GitHub has full App/installation APIs Local only returns empty GET /app/installations Minimal compatibility stub only Low PARTIAL
API discovery/meta/rate limit (root, meta, rate limit) Rich discovery/meta/rate-limit envelopes Discovery/meta are minimal/static; rate limit headers/body are local Static/minimal metadata Medium PARTIAL
OAuth/OIDC/connected login/agents (OAuth apps, device flow) GitHub OAuth/device flow uses GitHub identity; GitHub has no OIDC, connected-login, or agent binding routes Local has GitHub-like OAuth/device flow with PKCE authorization-code exchange, generic OIDC, connected-login callbacks, agent registration, invite/bind grants, bound-agent rename, token rotation, and renewable switch sessions Auth model intentionally diverges N/A Extension

Webhooks, Dependabot, Rulesets, Pages, Templates

Endpoint / Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
Repository webhooks (webhooks, config, deliveries) CRUD hooks, config get/update, ping/test, deliveries/redelivery CRUD and deliveries/redelivery supported Config endpoints, ping, and test routes are missing; delivery/payload semantics are local Medium PARTIAL
Dependabot alerts (repo, org, enterprise) Repo/org/enterprise alerts with filters/sort and dismiss/reopen Repo list/get/update supported Query filters ignored; org/enterprise alert endpoints missing Medium PARTIAL
Dependabot secrets (repo, org) Same caveats as secrets above Repo/org namespaced secret routes exist Selected repo single add/remove and exact encryption semantics missing Medium PARTIAL
Repository rulesets (rulesets, branch rules, rule suites) List/create/get/update/delete/history/rule suites List/create/get plus branch rule check Update/delete/history/rule suites missing; branch rule evaluation is basic Medium PARTIAL/GAP
Pages (site, builds, deployments, health) Get/create/update/delete Pages, list/create builds, build details, deployments, health Get/create/update/delete and list/create builds Latest/single build, deployments, health endpoints missing Medium PARTIAL
Licenses (list, get) GitHub has full license catalog Local embeds MIT, Apache-2.0, GPL-3.0 Catalog is tiny Low PARTIAL
Gitignore templates (list, get) Official template catalog Local embedded templates Catalog depends on local embedded files Low PARTIAL

GraphQL

Area Expected GitHub behavior Current behavior Gap Priority Status / Tests
Transport (docs) /graphql endpoint with schema-backed execution and standard GraphQL errors /api/graphql and /graphql endpoints with token auth; route by parsed fields/operation names Not a general GraphQL executor High PARTIAL
Introspection (schema, introspection) Full schema introspection __type returns selected field/enum lists for feature detection Full introspection queries are unsupported High PARTIAL
Queries (queries, objects, search) Viewer, repository owner, repo, issue, PR, labels, milestones, releases, search, projects, rulesets, Dependabot subset Supported subset for gh workflows Unsupported fields can be omitted or return empty data High PARTIAL
Mutations (docs) Broad GitHub mutation surface Supports selected issue, PR, repo, project, milestone, git database, labels, assignees, Dependabot, reaction, and lock mutations Many GitHub mutations are missing; some reaction mutations are minimal; project team linking explicitly unsupported High PARTIAL
Error semantics (errors, validation) GraphQL errors with paths/types and schema validation Mixed: some errResp, some graceful empty payloads Clients that rely on schema validation or exact error classes may misbehave Medium PARTIAL

Local Extension Route Index

This is the route index for the local product APIs summarized in the agent-native capability map. Treat these as AGS extensions, not GitHub-compatible endpoints:

Area Routes
Agents /api/v3/agents, /agent-invites, /agent-bindings/confirm, PATCH /agent-bindings/{agent_login}, /agent-bindings/{agent_login}/reset-token, /agent-bindings/{agent_login}/switch-session, /agent-bindings/{agent_login}/refresh-session, /user/agents
OAuth / OIDC / connected login /api/v3/oauth/device/approve, /api/v3/oauth/device/reject, /api/v3/oidc/device/code, /session, /callback, /lookup, /auth/connected/login, /auth/connected/callback
Analytics /api/v3/analytics/events
Presence/typing/read state /presence/heartbeat, /issues/{id}/typing, /issues/{issue_id}/presence, /users/{user_id}/last-seen, /user/presence/privacy, issue read-state routes
Attachments /api/v3/issues/{id}/attachments, /api/v3/repos/{owner}/{repo}/attachments, /api/v3/repositories/{repo_id}/attachments, /api/v3/attachments/{uuid}
Wiki /api/v3/repos/{owner}/{repo}/wiki/state, /wiki/tree, /wiki/reconcile/request, /wiki/reconcile, /wiki/compact, /wiki/compact/{jobID}, /wiki/pages..., /wiki/search, /wiki/move, /wiki/pages/{slug}/move, /wiki/pages/{slug}/backlinks, /wiki/pages/{slug}/history, /wiki/pages/{slug}/labels..., /api/v3/admin/wiki/repos/{owner}/{repo}/repair-locks
Org bootstrap POST /api/v3/user/orgs
Repo team sharing /api/v3/repos/{owner}/{repo}/team-sharing/enable
Local token management /api/v3/user/tokens

Remaining Gap Summary

  • Tighten search qualifier, ordering, and ranking parity across the implemented search endpoints.
  • Continue branch protection endpoint parity beyond the current monolithic route and selected subresources.
  • Expand deeper contents edge cases, commits, and release-asset response shapes for broader GitHub-compatible clients.
  • Revisit Actions, secrets, variables, and environments: many routes exist, but several are thin or locally mocked.
  • Treat GraphQL as a lightweight compatibility layer unless/until it is backed by a real schema/executor.
  • Keep local extensions clearly namespaced and out of GitHub compatibility claims.
  • Keep the generated /api/v3/openapi.json extension contract synchronized with this matrix when local extension behavior changes.