Skip to content

Commit f147938

Browse files
authored
feat(github): support scoped App installation credentials for project automation (#2316)
Fixes #2311 Add GitHub App installation credentials alongside explicit gh-cli profiles to the existing project GitHub brokers, Effects and audits. The host verifies installation/repository/permissions, signs RS256 JWTs, coalesces short-lived Token refreshes and handles private-key rotation. Human Owner/Maintainer selection uses the existing v1 service and durable receipts. Personal comments/reads retain independent user credentials; no Owner/ambient fallback. Publication and Release recovery fence identity changes while preserving candidate/test/Review evidence, repository capability checks and existing unknown-result reconciliation. Includes memory, architecture, operator guide, changelog and OpenAPI (29 queries, 34 commands, 186 dispatches). Dependency #2315 is merged. This PR now targets delivery/ai-centric-development-service. Head 3ab3a1d only adds the dependency merge parent; its tree 430d1af exactly equals the verified implementation d31ae60. No source content changed. Validation: full TZ=UTC npm run verify at d31ae60 passed 4783 tests, zero failures/skips, including six actual DSH runtime cases; OpenAPI3.1/JSON Schema and canonical source checks passed. Selected provider/runtime, local Git publication and durable selection/restart tests passed. Basic remote CI and tests-ok passed at the dependency-synchronization head (run41754260373). GitHub API responses and model inference are deterministic fixtures, explicitly separate from real service/protocol/filesystem/Git execution. Not run: actual GitHub App installation/write acceptance (requires separately authorized test App/repository), rollout or independent Reviewer PASS. No existing services, operator credentials or control-plane changes.
1 parent 75ca682 commit f147938

63 files changed

Lines changed: 2778 additions & 607 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/scripts/backend-docs.test.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ test('public API tables enumerate the actual complete command/query contracts',
1919
const commandText = api.split('## v1命令')[1].split('## Execution')[0]
2020
assert.deepEqual(rows(queryText), [...queries].sort())
2121
assert.deepEqual(rows(commandText), operations.filter(name => !queries.includes(name)).sort())
22-
assert.equal(queries.length, 28); assert.equal(rows(commandText).length, 33)
23-
for (const name of ['README.md', 'README.zh.md']) assert.match(read(name), /28查询\/33命令/)
22+
assert.equal(queries.length, 29); assert.equal(rows(commandText).length, 34)
23+
for (const name of ['README.md', 'README.zh.md']) assert.match(read(name), /29查询\/34命令/)
2424
})
2525

2626
test('quickstart JSON, shell syntax and local documentation links stay usable', () => {

‎PROJECT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ consultation store, committed Effects and scoped leases. Signed, explicitly
1515
verified Webhook notifications and native wakeups both lead to the same inbox
1616
service; private messages stay outside public SSE. [Contract](docs/agent-inbox.md).
1717
Actual isolated DSH/HTTP and a separate receiver pass with deterministic inference;
18-
live vendor acceptance and deployment remain separate. #2311 is the next credential-provider change.
18+
live vendor acceptance and deployment remain separate. #2311 adds App installation credentials alongside gh-cli, human-only connection selection, and original broker/Effects identity fencing. [Credential contract](docs/github-automation.md); live App acceptance needs authorized test resources.
1919

2020
#2300 publishes the source-matched public [OpenAPI contract](docs/openapi/flybot.openapi.json)
2121
and [third-party Bot guide](docs/third-party-bot-integration.md). Human-issued FBA scope,

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ HTTP 入口为 `POST /api/bot`、事件为 `GET /api/project-events`,
8181

8282
| 需要 | 文档 |
8383
| --- | --- |
84-
| 对象、权限、全部28查询/33命令、原生接口、幂等与SSE | [API参考](docs/development-service-api.md) |
84+
| 对象、权限、全部29查询/34命令、原生接口、幂等与SSE | [API参考](docs/development-service-api.md) |
8585
| Chief/角色/Task/Handoff、咨询、个人代理、安全与值守、状态与上下文 | [协作指南](docs/development-service-guide.md) |
8686
| 数据目录、账号平台、模型/SDK/仓库、停止重启、备份升级、排障 | [部署运维](docs/backend-operations.md) |
8787
| 个人Chief、多Bot、群聊、公共Bot、原版安装与桌面功能 | [原版FlyBot](README.native.zh.md) · [English](README.native.md) |
@@ -90,3 +90,5 @@ HTTP 入口为 `POST /api/bot`、事件为 `GET /api/project-events`,
9090

9191
真实部署入口是 `scripts/backend.mjs`。`dev/demo/` 是隔离开发验证工具,会使用测试模型或临时数据,不能作为生产启动方法。
9292
自动测试通过、真实 SDK 验证、浏览器验收、PR 合入与生产部署分别记录;本分支不承诺未验证的完整真实模型开发闭环。
93+
94+
项目自动化支持显式 gh-cli 或 GitHub App installation;人类选择已预置连接,个人用户授权独立。见 [GitHub配置与身份](docs/github-automation.md)。

‎README.zh.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ HTTP 入口为 `POST /api/bot`、事件为 `GET /api/project-events`,
8181

8282
| 需要 | 文档 |
8383
| --- | --- |
84-
| 对象、权限、全部28查询/33命令、原生接口、幂等与SSE | [API参考](docs/development-service-api.md) |
84+
| 对象、权限、全部29查询/34命令、原生接口、幂等与SSE | [API参考](docs/development-service-api.md) |
8585
| Chief/角色/Task/Handoff、咨询、个人代理、安全与值守、状态与上下文 | [协作指南](docs/development-service-guide.md) |
8686
| 数据目录、账号平台、模型/SDK/仓库、停止重启、备份升级、排障 | [部署运维](docs/backend-operations.md) |
8787
| 个人Chief、多Bot、群聊、公共Bot、原版安装与桌面功能 | [原版FlyBot](README.native.zh.md) · [English](README.native.md) |
@@ -90,3 +90,5 @@ HTTP 入口为 `POST /api/bot`、事件为 `GET /api/project-events`,
9090

9191
真实部署入口是 `scripts/backend.mjs`。`dev/demo/` 是隔离开发验证工具,会使用测试模型或临时数据,不能作为生产启动方法。
9292
自动测试通过、真实 SDK 验证、浏览器验收、PR 合入与生产部署分别记录;本分支不承诺未验证的完整真实模型开发闭环。
93+
94+
项目自动化支持显式 gh-cli 或 GitHub App installation;人类选择已预置连接,个人用户授权独立。见 [GitHub配置与身份](docs/github-automation.md)。

‎ROADMAP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
#2308 adds one native/external inbox protocol, verified Webhook hints, durable
66
processing and Chief continuation. Preserve existing personal Chief/group contracts;
77
do not turn consultations into Tasks or inbox claims into executor identity.
8-
Follow with #2311 GitHub App installation credentials alongside gh-cli; no live rollout.
8+
#2311 implements GitHub App credentials alongside gh-cli, scoped human selection and recovery fencing. Deterministic provider/runtime coverage is separate from real App acceptance; no live rollout.
99

1010
#2183 adds scoped agent credentials over the existing member-session HTTP channel,
1111
reuses per-participation safe/watch grants, and persists Task-origin provenance.

‎changelog.d/2311.added.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Support scoped GitHub App installation credentials alongside gh-cli for project reads, candidate publication and Release operations, with human-only connection selection, short-lived host credentials and identity-fenced recovery.

‎core/src/host/personal-agent-auth.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ export function install(rt) {
7676
const projectId = body.projectId ?? ownEntry(state.tasks, body.id ?? body.taskId)?.projectId ?? ownEntry(state.projectAttempts ?? {}, body.attemptId)?.projectId ?? ownEntry(state.projectQueue ?? {}, body.queueId)?.projectId ?? body.id
7777
const { grant } = scope(actor, projectId)
7878
const nativeWrite = ['task-create', 'task-update', 'task-cancel', 'task-answer-input'].includes(endpoint) || endpoint.startsWith('project-') && WORKBENCH_ENDPOINTS.has(endpoint) && !reserved.has(endpoint) && endpoint !== 'project-development' && endpoint !== 'project-agents'
79-
const developmentWrite = endpoint === 'project-development' && body.kind === 'command' && !['agent.mode', 'proposal.publish', 'inbox.connection.configure'].includes(body.name)
79+
const developmentWrite = endpoint === 'project-development' && body.kind === 'command' && !['agent.mode', 'proposal.publish', 'inbox.connection.configure', 'github.connection.configure'].includes(body.name)
8080
if (!grant || !nativeWrite && !developmentWrite) throw refusal('This agent operation requires authorized watch mode')
8181
}
8282
} catch (error) { return { ok: false, code: error.code ?? 'bot/forbidden', message: error.message } }

‎core/src/host/project-credentials.js‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { join } from 'node:path'
66
import { EffectDeferred, EffectCancelled } from './project-effects.js'
77
import { ownEntry, setEntry } from './store.js'
88
import { resolveGithubIdentity } from './project-github.js'
9+
import { createGithubConnections, projectGithubStatus } from './project-github-connections.js'
910
const refused = message => Object.assign(new Error(message), { code: 'bot/forbidden' })
1011

1112
export function createProjectCredentials(rt, { identity = resolveGithubIdentity, request = fetch } = {}) {
@@ -30,6 +31,7 @@ export function createProjectCredentials(rt, { identity = resolveGithubIdentity,
3031
try { project = rt.requireProjectAccess(actor, effect.projectId, 'create') }
3132
catch { throw new EffectCancelled('Comment Project authority was revoked') }
3233
const settings = personal(actor, effect.projectId)
34+
if (settings?.credential === 'github-app') throw new EffectCancelled('Personal operations require independent user credentials')
3335
if (project.repository !== effect.payload.repository || settings?.login?.toLowerCase() !== effect.payload.login.toLowerCase()) throw new EffectCancelled('Comment repository or personal identity changed')
3436
context.assertCurrent()
3537
return { actor, project, settings }
@@ -76,8 +78,9 @@ export function createProjectCredentials(rt, { identity = resolveGithubIdentity,
7678
const settings = personal(actor, projectId)
7779
if (endpoint === 'project-credential-status') return {
7880
personal: { configured: Boolean(settings?.credential && settings.configDir && settings.login), login: settings?.login ?? null },
79-
automation: { configured: Boolean(ownEntry(rt.config.projectRepositories ?? {}, project.repository)?.github?.credential && ownEntry(rt.config.projectRepositories ?? {}, project.repository)?.github?.configDir) },
81+
automation: projectGithubStatus(rt, project),
8082
}
83+
if (settings?.credential === 'github-app') throw refused('Personal operations require independent user credentials')
8184
if (body.scope !== undefined && body.scope !== 'personal') throw refused('This endpoint only uses your own personal GitHub identity')
8285
if (!settings?.login) throw refused('Personal GitHub credential is not configured for this human and Project')
8386
if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(project.repository ?? '')) throw refused('Project repository is unavailable')
@@ -121,4 +124,4 @@ export function createProjectCredentials(rt, { identity = resolveGithubIdentity,
121124
},
122125
}
123126
}
124-
export function install(rt) { rt.projectCredentials = createProjectCredentials(rt) }
127+
export function install(rt) { rt.projectCredentials = createProjectCredentials(rt); rt.projectGithubConnections = createGithubConnections(rt) }

‎core/src/host/project-delivery.js‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ import { createResourceWorkspaces, fileDigest } from './project-resource-workspa
1515
import { ROLE_POLICY_FILES, assembleRolePolicy, verifyRolePolicy, deliveryReviewReport, checkDevelopmentEvidence } from './project-role-policy.js'
1616
import { buildProjectContext, contextHash } from './project-role-context.js'
1717
import { githubPublisher } from './project-github.js'
18+
import { projectGithubSettings } from './project-github-connections.js'
19+
import { githubCredentialBinding } from './project-github-app.js'
1820
import { taskSessionId, confirmedWorkerExit, pinTaskRoleDefinition, discardUnpreparedTaskDefinitions } from './project-task-sessions.js'
1921
import { readMergeHeads } from './project-merge-heads.js'
2022
import { childResultSources, createChildInputAdmission } from './project-child-inputs.js'
@@ -68,11 +70,13 @@ export function createProjectDelivery(rt, { publisher, releaseProvider } = {}) {
6870
const taskOf = id => ownEntry(state.tasks, String(id ?? ''))
6971
const projectOf = (id, attempt) => { const project = rt.projects.repository.get(id, { includeDeleted: true }); return attempt ? attemptProject(rt, project, attempt) : project }
7072
const settingsOf = project => repositorySettings(rt, project)
71-
const publisherOf = project => publisher ?? githubPublisher(settingsOf(project).github)
73+
const publisherOf = (project, authorize) => { settingsOf(project); return publisher ?? githubPublisher(projectGithubSettings(rt, project), { authorize }) }
7274
const releases = createProjectReleases(rt, { projectOf, ...(releaseProvider ? { providerFactory: () => releaseProvider } : {}) })
7375
async function validatePublication(effect, context) {
7476
const attempt = ownEntry(attempts(), effect.payload.attemptId), task = taskOf(effect.taskId)
77+
if (attempt?.publicationCredential && attempt.publicationCredential !== githubCredentialBinding(projectGithubSettings(rt, projectOf(attempt.projectId, attempt)), attempt.requirement.repository ?? projectOf(attempt.projectId, attempt).repository)) throw new EffectCancelled('Publication GitHub connection changed; reconcile with the original identity')
7578
if (!attempt || attempt.projectId !== effect.projectId || task?.deliveryAttemptId !== attempt.id || attempt.candidateSha !== effect.payload.candidateSha || ['accepted', 'cancelled'].includes(task.status) || attempt.cancelRequested) throw new EffectCancelled('Publication candidate was stopped, superseded or ended')
79+
settingsOf(projectOf(attempt.projectId, attempt))
7680
try {
7781
await rt.projectDelegations?.background(effect.payload.initiatedBy, task.collaboration?.sourceSessionId)
7882
rt.requireProjectAccess({ memberId: effect.payload.initiatedBy }, effect.projectId, 'task-write', task)
@@ -99,7 +103,7 @@ export function createProjectDelivery(rt, { publisher, releaseProvider } = {}) {
99103
if (!context.inline) await validatePublication(effect, context)
100104
context.assertCurrent()
101105
const attempt = ownEntry(attempts(), effect.payload.attemptId)
102-
await publishNow(attempt)
106+
await publishNow(attempt, async () => { await validatePublication(effect, context) })
103107
return structuredClone(attempt.pr)
104108
}
105109
return context.inline ? publish() : serialAttempt(effect.payload.attemptId, publish)
@@ -141,6 +145,7 @@ export function createProjectDelivery(rt, { publisher, releaseProvider } = {}) {
141145
async function publicationOf(previous, project) {
142146
if (!previous) return undefined
143147
if (previous.publicationEffectId && !previous.pr) throw reject('Previous publication is unresolved; reconcile its existing effect before creating rework')
148+
if (previous.publicationCredential && previous.publicationCredential !== githubCredentialBinding(projectGithubSettings(rt, project), project.repository)) throw reject('Previous publication GitHub connection changed; reconcile before rework')
144149
const binding = previous.pr ? { number: previous.pr.number, repository: previous.pr.repository, branch: previous.publicationBinding?.branch ?? previous.branch, previousSha: previous.candidateSha } : structuredClone(previous.publicationBinding)
145150
if (binding && (binding.repository !== project.repository || !Number.isSafeInteger(binding.number) || binding.number < 1 || typeof binding.branch !== 'string' || !binding.branch || !/^[a-f0-9]{40}$/.test(binding.previousSha) || previous.pr && previous.pr.sha !== previous.candidateSha)) throw reject('Existing delivery PR binding is inconsistent; reconcile before rework')
146151
if (binding) {
@@ -569,6 +574,11 @@ export function createProjectDelivery(rt, { publisher, releaseProvider } = {}) {
569574
await publishVerified(attempt)
570575
}
571576
async function publishVerified(attempt) {
577+
if (!publisher) {
578+
const project = projectOf(attempt.projectId, attempt), binding = githubCredentialBinding(projectGithubSettings(rt, project), project.repository)
579+
if (attempt.publicationCredential && attempt.publicationCredential !== binding) throw reject('Publication GitHub connection changed; reconcile before retry')
580+
if (!attempt.publicationCredential) { attempt.publicationCredential = binding; await rt.save() }
581+
}
572582
if (!rt.projectEffects) return publishNow(attempt)
573583
const task = taskOf(attempt.taskId)
574584
const spec = { kind: 'github.publish', key: `${attempt.id}:${attempt.candidateSha}`, projectId: attempt.projectId, taskId: attempt.taskId,
@@ -577,8 +587,15 @@ export function createProjectDelivery(rt, { publisher, releaseProvider } = {}) {
577587
attempt.publicationEffectId = token.id
578588
return rt.projectEffects.perform(spec)
579589
}
580-
async function publishNow(attempt) {
581-
const pr = await publisherOf(projectOf(attempt.projectId, attempt)).publish(attempt, projectOf(attempt.projectId, attempt))
590+
async function publishNow(attempt, authorize) {
591+
const project = projectOf(attempt.projectId, attempt)
592+
const check = async () => {
593+
if (authorize) await authorize()
594+
settingsOf(projectOf(attempt.projectId, attempt))
595+
if (attempt.cancelRequested || taskOf(attempt.taskId)?.deliveryAttemptId !== attempt.id) throw reject('Publication Task changed')
596+
if (attempt.publicationCredential && attempt.publicationCredential !== githubCredentialBinding(projectGithubSettings(rt, projectOf(attempt.projectId, attempt)), project.repository)) throw reject('Publication GitHub connection changed')
597+
}
598+
const pr = await publisherOf(project, check).publish(attempt, projectOf(attempt.projectId, attempt))
582599
if (pr.sha !== attempt.candidateSha || attempt.publicationBinding && (pr.number !== attempt.publicationBinding.number || pr.repository !== attempt.publicationBinding.repository)) throw reject('Published PR does not match candidate or existing binding')
583600
if (attempt.cancelRequested) throw reject('Delivery was stopped')
584601
attempt.pr = pr

0 commit comments

Comments
 (0)