@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/external/github-integration-design.md

@@ -0,0 +1,151 @@
+# GitHub integration design
+
+## Purpose
+
+GitHub is the first full external backend provider for Krate. It can support all three unified interfaces: issue tracking, CI/CD, and git forge. Krate should integrate through a GitHub App by default, with optional user-attributed actions when a user token is available and admitted.
+
+## Authentication model
+
+Preferred auth:
+
+```yaml
+kind: ExternalBackendProvider
+spec:
+  providerType: github
+  auth:
+    mode: github-app
+    appIdSecretRef:
+      name: github-app-a5c
+      key: app-id
+    privateKeySecretRef:
+      name: github-app-a5c
+      key: private-key.pem
+    webhookSecretRef:
+      name: github-app-a5c
+      key: webhook-secret
+```
+
+Flow:
+
+1. Krate signs a GitHub App JWT.
+2. Krate exchanges it for installation access tokens per org/repository installation.
+3. Tokens are cached only until expiry and never stored in status.
+4. User-attributed actions use GitHub App user access tokens when available and required.
+5. All actions still pass Krate org/RBAC/admission checks.
+
+## GitHub provider capabilities
+
+```yaml
+capabilities:
+  issueTracking:
+    issues: true
+    comments: true
+    labels: true
+    milestones: true
+    projects: optional
+  cicd:
+    actionsWorkflowRuns: true
+    workflowJobs: true
+    checks: true
+    statuses: true
+    selfHostedRunners: optional
+  gitForge:
+    repositories: true
+    pullRequests: true
+    reviews: true
+    refs: true
+    commits: true
+    deployKeys: true
+    branchProtection: true
+    collaborators: true
+```
+
+## Installation binding
+
+```yaml
+kind: ExternalBackendBinding
+spec:
+  organizationRef: a5c
+  providerRef: github-a5c
+  externalRef:
+    owner: a5c-ai
+    repository: krate
+    installationId: 123456
+  interfaces:
+    issueTracking:
+      enabled: true
+      mode: bidirectional
+    cicd:
+      enabled: true
+      mode: external-owned
+    gitForge:
+      enabled: true
+      mode: bidirectional
+```
+
+## Webhook events
+
+Recommended GitHub events:
+
+| Interface | Events |
+| --- | --- |
+| Issue tracking | `issues`, `issue_comment`, `label`, `milestone`, `projects_v2_item` where available. |
+| CI/CD | `workflow_run`, `workflow_job`, `check_run`, `check_suite`, `status`, `push`. |
+| Git forge | `repository`, `pull_request`, `pull_request_review`, `pull_request_review_comment`, `push`, `create`, `delete`, `branch_protection_rule`, `deploy_key`. |
+| Provider lifecycle | `installation`, `installation_repositories`, `meta`. |
+
+Webhook delivery handling:
+
+- validate signature before parsing;
+- record delivery ID and event type;
+- respond quickly with 2XX after enqueue;
+- process asynchronously through Krate queue/controller;
+- dedupe by provider, delivery ID, event, and installation;
+- support redelivery and replay.
+
+## Backfill and repair
+
+Backfill should run when:
+
+- provider binding is created;
+- webhook delivery is missed or failed;
+- rate limit window recovers;
+- manual `resync` is requested;
+- native object has stale `lastSyncedAt`;
+- provider installation changes repository access.
+
+GitHub backfill strategy:
+
+- GraphQL for list hydration where it reduces calls and provides cursors;
+- REST for endpoints with first-class Actions, checks, deploy keys, webhooks, branch protection, and logs;
+- conditional requests with ETags where useful;
+- rate-limit aware scheduling by installation and org.
+
+## Write paths
+
+| Action | Default mode |
+| --- | --- |
+| create/update issue | write-through or reviewed-write by policy. |
+| comment on issue/PR | write-through for humans, reviewed-write for agents. |
+| update labels | bidirectional with conflict detection. |
+| rerun/cancel workflow | write-through after permission review. |
+| create/update PR | reviewed-write for agents; write-through for authorized humans. |
+| merge PR | external-owned or reviewed-write; require branch protection status. |
+| deploy key update | Krate-owned or reviewed-write. |
+| branch protection update | reviewed-write unless org policy says Krate-owned. |
+
+## GitHub-specific conflicts
+
+- Issue and PR share number namespace; PR-backed issue projections must link to PR.
+- Labels can be edited externally while Krate has pending desired changes.
+- Branch protection fields may not map 1:1 to Krate `RefPolicy`.
+- Workflow runs may be rerun externally while Krate still shows an old attempt.
+- Force-push updates PR head SHA and invalidates cached diff/check context.
+
+## UI requirements
+
+- Provider setup wizard for GitHub App app ID, private key, webhook secret, installation ID, owner, repository selection, and selected interfaces.
+- Repository settings page shows GitHub binding and per-interface mode.
+- Issue/PR/run pages show native GitHub link, sync status, and conflict banner.
+- Actions/runs page can filter external GitHub Actions vs Krate-native pipelines.
+- Webhook page shows delivery IDs, replay, redelivery, and backfill status.

package/docs/external/issue-tracking-interface.md

@@ -0,0 +1,66 @@
+# Issue tracking interface
+
+## Purpose
+
+The issue tracking interface syncs externally managed work items into Krate and optionally writes changes back. It covers issues, comments, labels, milestones, assignees, projects, saved views, reactions, and issue events.
+
+## Provider contract
+
+A provider implementing this interface should support some or all of:
+
+```ts
+interface IssueTrackingProvider {
+  listIssues(cursor): Page<ExternalIssue>;
+  getIssue(ref): ExternalIssue;
+  createIssue(input): ExternalIssue;
+  updateIssue(ref, patch): ExternalIssue;
+  closeIssue(ref, reason): ExternalIssue;
+  listComments(issueRef, cursor): Page<ExternalComment>;
+  createComment(issueRef, input): ExternalComment;
+  updateComment(commentRef, patch): ExternalComment;
+  listLabels(cursor): Page<ExternalLabel>;
+  syncLabels(desired): SyncResult;
+  listEvents(issueRef, cursor): Page<ExternalIssueEvent>;
+}
+```
+
+Capabilities are negotiated; read-only providers can omit mutating operations.
+
+## Resource mapping
+
+| External concept | Krate resource/projection |
+| --- | --- |
+| issue/work item | `Issue` |
+| issue comment | `IssueComment` aggregated projection or `Issue.status.comments` summary |
+| label | `IssueLabel` config/projection or labels on `Issue` |
+| milestone | `Milestone` projection or metadata field |
+| assignee | `User`/`Team` references plus external identity mapping |
+| project field | `View`, `Selector`, or provider-specific field projection |
+| linked PR | `PullRequest` edge |
+| issue event | `ExternalSyncEvent` or issue activity stream |
+
+## GitHub mapping
+
+GitHub Issues map naturally to Krate `Issue`. GitHub pull requests also have issue numbers and issue-like comments/labels, so the GitHub issue provider must avoid duplicating PR-backed issues. A GitHub issue with `pull_request` metadata should link to the `PullRequest` projection rather than become an independent work item unless the UI explicitly needs a combined activity view.
+
+## Sync rules
+
+- Webhooks handle `issues`, `issue_comment`, `label`, `milestone`, and assignment events.
+- Backfill/poll handles missed events and periodic consistency checks.
+- Cursor sync stores provider cursor or `updated_at` high-water mark.
+- Writes include idempotency keys where provider supports them; otherwise Krate stores write intent and native result.
+- Conflicts create `ExternalSyncConflict` when local desired state and external state both changed since last sync.
+
+## User-facing changes
+
+- Issue pages show external provider badges, native URLs, sync status, and conflict state.
+- Editing an externally owned issue shows whether the change writes through, opens a reviewed change, or is disabled.
+- Comments show source: Krate, GitHub, imported, or agent.
+- Label management shows external ownership and drift.
+
+## Acceptance criteria
+
+- A read-only issue provider can mirror issues and comments without write permissions.
+- A bidirectional provider can update title/body/state/labels/comments and detect conflicts.
+- GitHub PR-backed issues link to PRs instead of duplicating work items.
+- Webhook replay and cursor backfill converge to the same state.

package/docs/external/provider-capability-manifests.md

@@ -0,0 +1,204 @@
+# Provider capability manifests
+
+## Purpose
+
+Provider manifests make external backend support data-driven. Each adapter declares supported interfaces, operations, auth modes, webhook events, rate-limit model, object identity fields, and unsupported features. Krate uses the manifest to render UI, validate CRDs, run contract tests, and disable unsupported actions.
+
+## Manifest schema
+
+```yaml
+apiVersion: krate.a5c.ai/v1alpha1
+kind: ExternalProviderCapabilityManifest
+metadata:
+  name: github-v1
+spec:
+  providerType: github
+  displayName: GitHub
+  hosting:
+    - saas
+    - github-enterprise-server
+  authModes:
+    - github-app
+    - oauth-user
+  api:
+    rest: true
+    graphql: true
+    webhook: true
+  identity:
+    nativeIdFields: [id, number]
+    globalIdField: node_id
+    urlField: html_url
+    versionFields: [etag, updated_at, head_sha]
+  interfaces: {}
+```
+
+## Operation shape
+
+```yaml
+operation: createPullRequest
+supported: true
+write: true
+requires:
+  permissions:
+    - gitForge.pullRequests.write
+  authModes:
+    - github-app
+    - oauth-user
+  nativeScopes:
+    - pull_requests:write
+idempotency:
+  mode: synthetic-key
+rateLimitCost:
+  restRequests: 1
+webhookConfirmation:
+  events: [pull_request]
+```
+
+## GitHub manifest sketch
+
+```yaml
+providerType: github
+interfaces:
+  issueTracking:
+    supported: true
+    objects: [Issue, IssueComment, Label, Milestone]
+    operations:
+      - listIssues
+      - getIssue
+      - createIssue
+      - updateIssue
+      - closeIssue
+      - listComments
+      - createComment
+      - updateComment
+      - listLabels
+      - syncLabels
+    webhooks: [issues, issue_comment, label, milestone]
+  cicd:
+    supported: true
+    objects: [WorkflowRun, WorkflowJob, CheckRun, CheckSuite, CommitStatus, Runner]
+    operations:
+      - listWorkflowRuns
+      - getWorkflowRun
+      - listWorkflowJobs
+      - rerunWorkflowRun
+      - cancelWorkflowRun
+      - listSelfHostedRunners
+      - createCheckRun
+      - updateCheckRun
+    webhooks: [workflow_run, workflow_job, check_run, check_suite, status]
+  gitForge:
+    supported: true
+    objects: [Repository, PullRequest, Review, Ref, Commit, DeployKey, BranchProtection, Collaborator]
+    operations:
+      - listRepositories
+      - getRepository
+      - createRepository
+      - updateRepository
+      - listPullRequests
+      - createPullRequest
+      - updatePullRequest
+      - mergePullRequest
+      - listRefs
+      - getCommit
+      - syncDeployKeys
+      - syncBranchProtection
+    webhooks: [repository, pull_request, pull_request_review, pull_request_review_comment, push, create, delete, deploy_key, branch_protection_rule]
+```
+
+## GitLab manifest sketch
+
+```yaml
+providerType: gitlab
+hosting: [saas, self-managed]
+authModes: [oauth-user, project-token, group-token, personal-access-token]
+interfaces:
+  issueTracking:
+    supported: true
+    objects: [Issue, Note, Label, Milestone]
+    webhooks: [Issues Hook, Note Hook]
+  cicd:
+    supported: true
+    objects: [Pipeline, Job, Artifact, Runner]
+    webhooks: [Pipeline Hook, Job Hook]
+  gitForge:
+    supported: true
+    objects: [Project, MergeRequest, Approval, Branch, Tag, DeployKey, ProtectedBranch]
+    webhooks: [Push Hook, Tag Push Hook, Merge Request Hook]
+```
+
+## Jira manifest sketch
+
+```yaml
+providerType: jira
+hosting: [cloud, data-center]
+interfaces:
+  issueTracking:
+    supported: true
+    objects: [Issue, Comment, Project, Component, Version, Sprint, Board]
+    operations: [listIssues, getIssue, createIssue, updateIssue, transitionIssue, createComment, updateComment]
+    webhooks: [issue_created, issue_updated, issue_deleted, comment_created, comment_updated]
+  cicd:
+    supported: false
+  gitForge:
+    supported: false
+notes:
+  bodyFormat: atlassian-document-format
+```
+
+## Buildkite manifest sketch
+
+```yaml
+providerType: buildkite
+interfaces:
+  issueTracking:
+    supported: false
+  cicd:
+    supported: true
+    objects: [Pipeline, Build, Job, Agent, Artifact]
+    operations: [listPipelines, listBuilds, getBuild, listJobs, getLog, rebuildBuild, cancelBuild, listAgents]
+    webhooks: [build.scheduled, build.running, build.finished, job.finished]
+  gitForge:
+    supported: false
+```
+
+## Custom provider manifest
+
+Custom providers must declare exact operations and webhook normalization rules:
+
+```yaml
+providerType: custom
+adapterRef:
+  package: '@a5c-ai/krate-provider-acme'
+  version: 1.x
+interfaces:
+  issueTracking:
+    supported: true
+    operations: [listIssues, getIssue]
+  cicd:
+    supported: false
+  gitForge:
+    supported: false
+```
+
+## UI use
+
+The UI uses manifests to:
+
+- show only supported interface checkboxes;
+- explain unsupported actions;
+- choose auth forms;
+- show webhook event requirements;
+- render provider-specific object labels;
+- warn when selected sync mode requires unsupported write operations;
+- drive setup wizard validation.
+
+## Test use
+
+Contract tests use manifests to:
+
+- generate provider capability tests;
+- assert unsupported operations are disabled;
+- run shared interface suites only for supported interfaces;
+- validate provider fixture completeness;
+- verify webhook event normalization coverage.

package/docs/external/provider-catalog.md

@@ -0,0 +1,139 @@
+# Pluggable backend provider catalog
+
+## Purpose
+
+This catalog lists likely external backend integrations and how each maps to Krate's three unified interfaces:
+
+1. issue tracking;
+2. CI/CD;
+3. git forge.
+
+A backend can support one, two, or all three. Provider implementations should be capability-driven rather than hard-coded to GitHub semantics.
+
+## Provider matrix
+
+| Provider | Issue tracking | CI/CD | Git forge | Notes |
+| --- | --- | --- | --- | --- |
+| GitHub | yes | yes | yes | first full provider; GitHub Apps, REST, GraphQL, webhooks, Actions, Checks. |
+| GitLab | yes | yes | yes | issues, merge requests, pipelines/jobs, webhooks, project/group APIs; supports SaaS and self-managed. |
+| Bitbucket Cloud | limited/yes | yes | yes | repositories, pull requests, pipelines, webhooks; issue support depends on workspace/repo configuration. |
+| Bitbucket Data Center | limited/yes | external/limited | yes | repo/PR APIs and webhooks; CI often external Jenkins/Bamboo. |
+| Azure DevOps | yes | yes | yes | Work Items, Boards, Git repos/PRs, Pipelines, service hooks. |
+| Jira Cloud/Data Center | yes | no | no | work items/issues only; pairs well with GitHub/GitLab/Bitbucket or CI-only providers. |
+| Linear | yes | no | no | GraphQL issue/workflow model and webhooks; no native git forge. |
+| Buildkite | no | yes | no | builds, jobs, agents, artifacts, webhooks; pairs with GitHub/GitLab/Bitbucket. |
+| CircleCI | no | yes | no | pipelines, workflows, jobs, webhooks, artifacts; pairs with git forge providers. |
+| Jenkins | no | yes | no | jobs/builds/logs via remote API; webhook support usually plugin-specific. |
+| Gitea | yes | limited/external | yes | current internal/default forge path; can also be external-managed. |
+| Gerrit | no/limited | no | yes | code review and Git refs; often pairs with Jenkins/Buildkite. |
+| Raw Git server | no | no | partial | clone/fetch/push/refs only; no issue/PR semantics unless paired. |
+| Custom webhook backend | optional | optional | optional | provider adapter can normalize proprietary events into one interface. |
+
+## Provider profiles
+
+### Full forge providers
+
+Full forge providers typically implement all three interfaces:
+
+- GitHub;
+- GitLab;
+- Azure DevOps;
+- partially Bitbucket when issue and pipeline features are enabled.
+
+These providers can power repository pages end to end, but Krate should still let each interface be enabled independently.
+
+### Work tracking providers
+
+Work tracking providers implement issue tracking only:
+
+- Jira;
+- Linear;
+- Azure Boards if used separately from Azure Repos/Pipelines;
+- custom ticket systems.
+
+Krate maps these into issues/work items, labels, project fields, comments, assignees, and issue-triggered agent dispatch.
+
+### CI/CD providers
+
+CI/CD providers implement pipeline/job/run functionality only:
+
+- Buildkite;
+- CircleCI;
+- Jenkins;
+- Azure Pipelines if used separately;
+- GitHub Actions if GitHub forge is not used;
+- GitLab CI if GitLab forge is not used.
+
+Krate maps these into `Pipeline`, `Job`, logs, artifacts, checks, runners, and triggers.
+
+### Git forge providers
+
+Git forge providers implement repos/PRs/refs/keys but may not own issues or CI:
+
+- GitHub;
+- GitLab;
+- Bitbucket;
+- Gitea;
+- Gerrit;
+- raw Git with limited semantics.
+
+Krate maps these into repositories, pull requests/reviews, refs, commits, deploy keys, repository permissions, and branch protection.
+
+## Capability descriptor
+
+Each provider adapter should expose a descriptor:
+
+```yaml
+providerType: gitlab
+version: v1
+interfaces:
+  issueTracking:
+    supported: true
+    operations: [list, get, create, update, comment, label, transition]
+    webhookEvents: [issue, note]
+  cicd:
+    supported: true
+    operations: [listRuns, getRun, listJobs, getLog, retry, cancel]
+    webhookEvents: [pipeline, job]
+  gitForge:
+    supported: true
+    operations: [listRepos, getRepo, listPullRequests, createPullRequest, merge, listRefs]
+    webhookEvents: [push, mergeRequest, tagPush]
+authModes: [oauth-app, personal-token, project-token, self-managed-token]
+hosting: [saas, self-managed]
+rateLimitModel: provider-specific
+```
+
+## Provider-specific notes
+
+### GitLab
+
+GitLab should support issues, merge requests, pipelines/jobs, project/group webhooks, branches/tags, approvals, protected branches, deploy keys, and self-managed base URLs.
+
+### Bitbucket
+
+Bitbucket should separate Cloud and Data Center adapters because authentication, APIs, webhook payloads, and feature availability differ.
+
+### Jira
+
+Jira issue payloads use Atlassian Document Format for rich text in Cloud REST v3. Krate needs a markdown/ADF conversion layer for issue body/comments.
+
+### Linear
+
+Linear is GraphQL-first and issue/workflow-oriented. It should support issue tracking with webhooks and a provider-specific field mapping for teams, cycles, projects, states, and labels.
+
+### Azure DevOps
+
+Azure DevOps can support all three interfaces, but Work Items, Git repos/PRs, Pipelines, and Service Hooks are separate service areas. Krate should model them under one provider with separate interface credentials/scopes where needed.
+
+### Buildkite/CircleCI/Jenkins
+
+These are CI/CD-only providers. They should map to `Pipeline`/`Job` and can be paired with GitHub/GitLab/Bitbucket/Gitea for repo and PR context.
+
+## Acceptance criteria
+
+- Provider adapter selection is capability-driven.
+- A single Krate repository can bind different providers per interface.
+- A provider can be self-managed with custom base URLs.
+- UI can explain unsupported operations before a user clicks them.
+- Tests can run provider contract suites against fake adapters for each interface.

package/docs/external/provider-rollout-testing.md

@@ -0,0 +1,78 @@
+# Provider rollout and testing
+
+## Purpose
+
+This document defines implementation slices and QA coverage for GitHub and future providers.
+
+## Rollout slices
+
+### Slice 1: provider registry and read-only GitHub binding
+
+- Add `ExternalBackendProvider`, `ExternalBackendBinding`, and sync policy resources.
+- Configure GitHub App Secret metadata.
+- Validate auth and installation access.
+- Show provider in org settings.
+
+### Slice 2: git forge read sync
+
+- Sync repositories and pull requests read-only.
+- Store external IDs and native URLs.
+- Show GitHub badges and links.
+- Backfill plus webhook convergence tests.
+
+### Slice 3: issue tracking sync
+
+- Sync issues, comments, labels, milestones.
+- Handle PR-backed issue identity.
+- Add issue write-through for authorized humans.
+
+### Slice 4: CI/CD sync
+
+- Sync workflow runs, jobs, checks, statuses.
+- Show GitHub Actions runs beside Krate pipelines.
+- Add logs/artifacts lazy fetch.
+
+### Slice 5: write intents and conflicts
+
+- Add reviewed-write and write-through actions.
+- Add `ExternalWriteIntent` and `ExternalSyncConflict` UI.
+- Add agent write-back approval flow.
+
+### Slice 6: runner and advanced repo management
+
+- Self-hosted runner inventory/registration if enabled.
+- Deploy keys, collaborators, and branch protection sync.
+- Rate-limit aware bulk backfill.
+
+## Test coverage
+
+| Slice | Required tests |
+| --- | --- |
+| provider registry | auth Secret metadata, missing Secret, bad installation, no-token leak. |
+| git forge read | repo/PR backfill, webhook update, duplicate delivery, cross-org denial. |
+| issue sync | issue/comment/label update, PR-backed issue link, conflict. |
+| CI/CD sync | workflow/job/check event, rerun/cancel permission, log lazy fetch. |
+| write intents | approval required, provider write failure, confirmation, conflict. |
+| advanced repo | deploy key sync, branch protection drift, runner registration token no-leak. |
+
+## Fixtures
+
+Add fixtures for:
+
+- GitHub App provider Secret metadata;
+- installation binding;
+- repository webhook payloads;
+- issue/comment/label payloads;
+- pull request/review payloads;
+- workflow run/job/check payloads;
+- deploy key/branch protection payloads;
+- rate limit and abuse-limit responses;
+- redelivery payloads.
+
+## Acceptance criteria
+
+- GitHub can be enabled for one org/repository with selected interfaces.
+- A provider implementing only one interface can still be represented.
+- Webhook replay and backfill converge.
+- Bidirectional writes are explicit, permission-checked, and audited.
+- Future providers can be added by implementing one or more provider contracts.

package/docs/external/research-results.md

@@ -0,0 +1,48 @@
+# Research results
+
+## Purpose
+
+This document records the GitHub research used to design Krate external backend integration. It intentionally focuses on official GitHub surfaces and the implications for Krate's provider abstractions.
+
+## GitHub integration surfaces
+
+| Surface | Relevant GitHub capability | Krate implication |
+| --- | --- | --- |
+| GitHub Apps | authenticate as app, installation, or user; installation tokens; permission-scoped access | use GitHub App installation as default automation identity; use user tokens only for actor-attributed actions. |
+| REST API | repositories, issues, pull requests, Actions, checks, webhooks, deploy keys, refs, commits | implement provider connectors with endpoint-specific permissions and rate-limit handling. |
+| GraphQL API | precise data selection, node IDs, connections/cursors | use for efficient list/detail sync, cross-object hydration, and stable global IDs. |
+| Webhooks | repository/org/app events with payloads and delivery IDs | use webhook-first sync for freshness and as trigger source. |
+| Webhook delivery APIs | recent delivery inspection and redelivery | support replay/recovery and delivery audit. |
+| Actions APIs | workflows, workflow runs, jobs, logs, self-hosted runners | map GitHub Actions into Krate pipeline/job/runner abstractions. |
+| Checks/status APIs | checks, statuses, workflow check suites/runs | map external checks into Krate CI status and PR gates. |
+| Deploy keys and Git access | repository-scoped SSH deploy keys and installation-token HTTP Git access | support external Git checkout/mirroring without PATs. |
+
+## Key findings
+
+- GitHub's REST API covers repository management, issue management, pull requests/reviews, workflow runs, self-hosted runners, checks, deploy keys, refs, commits, and repository webhooks.
+- GitHub webhooks should be subscribed narrowly; GitHub documents using secrets, HTTPS, event/action filtering, unique delivery IDs, fast 2XX responses, queues for asynchronous processing, and redelivery for recovery.
+- GitHub App installation tokens expire and are permission-bound; user access tokens can attribute user actions but are limited by both app permissions and user permissions.
+- GitHub GraphQL exposes precise object selection, node IDs, connections, and cursors; REST payloads often include `node_id`, which can bridge REST and GraphQL identities.
+- GitHub Actions workflow runs can be viewed, rerun, canceled, and logged through REST; self-hosted runners can be listed, registered, and deleted through Actions APIs.
+- GitHub pull requests are issue-like for labels, assignees, milestones, and comments, so issue and pull-request sync must coordinate shared issue-number identity.
+- GitHub deploy keys are repository-scoped SSH keys and are separate from GitHub App installation-token HTTP Git access.
+
+## Sources
+
+- GitHub REST API overview and repository endpoints.
+- GitHub Issues REST endpoints.
+- GitHub Pull Requests REST endpoints.
+- GitHub Actions workflow run, workflow, checks, and self-hosted runner endpoints.
+- GitHub Webhooks docs: events/payloads, best practices, validation, deliveries, redelivery.
+- GitHub Apps auth docs: app JWT, installation tokens, user tokens, permissions.
+- GitHub GraphQL docs: node IDs, precise queries, cursor pagination, schema.
+
+## Design impact
+
+Krate should not create a GitHub-only data model. Instead, GitHub is the first provider implementation of three interfaces:
+
+1. issue tracking provider;
+2. CI/CD provider;
+3. git forge provider.
+
+GitHub can support all three. Other providers may only support one or two. For example, Jira may support issue tracking only; Buildkite may support CI/CD only; a raw Git server may support git forge only.