feat(deploy): inherit GitHub App installations

[kjgbot]

Phase

Phase 5 — seamless GitHub App installation flow wiring (workforce CLI companion).

Summary

• Extends relayfileIntegrationResolver for default GitHub deployer-user connects to opt into cloud's GitHub installation flow.
• Opens GitHub user OAuth, polls /github/reconcile, and calls /github/join when an organization already has the App.
• Falls back to the normal github-relay install session when the flow is disabled or no inheritable organization installation is found.
• Leaves explicit workspace and workspace-service-account GitHub connect request bodies unchanged.

Gate evidence

• Fresh worktree off workforce origin/main 644c3b0.
• pnpm install --frozen-lockfile passed.
• pnpm --filter @agentworkforce/persona-kit build && pnpm --filter @agentworkforce/runtime build && pnpm --filter @agentworkforce/deploy build passed.
• pnpm --filter @agentworkforce/deploy test passed: 178 tests.
• git diff --check passed.

User-visible gate

• Deploy against a workspace whose org already has the GitHub App now prints integrations.github: already connected via <org>; using <workspace> and does not request a fresh install session.

Linked PRs

• Cloud Phase 5 PR: https://github.com/AgentWorkforce/cloud/pull/2022

Rollback

• Revert this PR to restore the generic GitHub connect-session flow in the CLI.
• Cloud flag-off behavior remains the legacy install flow.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[codeant-ai]

Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI.

[coderabbitai]

Warning

Review limit reached

@agent-relay-code[bot], we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 7 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 42129e7f-7069-44c1-bacb-3241095517ea

📥 Commits

Reviewing files that changed from the base of the PR and between 06e2edb and f3668a8.

📒 Files selected for processing (2)

• packages/deploy/src/connect.test.ts
• packages/deploy/src/connect.ts

📝 Walkthrough

Walkthrough

This PR adds support for GitHub App installation inheritance in the relayfile deploy connector. When connecting GitHub via deployer-user scope, the client now opts into an installation flow that attempts to reuse existing org installations before falling back to fresh authentication, with end-to-end test coverage.

Changes

GitHub App Installation Connection Flow

Layer / File(s)	Summary
Installation flow request opt-in packages/deploy/src/connect.ts	Client signals installation-flow capability by including githubInstallationFlow: true in the initial connect-session request for GitHub with deployer-user scope.
Installation inheritance and fallback orchestration packages/deploy/src/connect.ts	After receiving the connect-session response, the code reads the githubInstallationFlow flag and attempts to inherit an existing org installation; if no match is found, it requests a fresh install session and uses the returned URL for browser opening.
GitHub reconciliation and join polling helpers packages/deploy/src/connect.ts	New polling functions tryConnectExistingGithubInstallation(), readGithubReconcile(), and postGithubJoin() interact with cloud endpoints to find non-suspended organization matches, handle join outcomes, return installation-based connection IDs, and timeout gracefully if no inheritance succeeds.
Test coverage for installation flow packages/deploy/src/connect.test.ts	New test case mocks the installation-flow path with reconcile/join responses, verifies the returned installation-based connection ID and log message; existing default-source test updated to expect githubInstallationFlow: true in the request body.

🎯 4 (Complex) | ⏱️ ~45 minutes

🐰 A rabbit hops through the installation flow,
No fresh auth needed when orgs already know,
Reconcile and join with a polling embrace,
Finding the right org in the right place!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(deploy): inherit GitHub App installations' directly and concisely summarizes the main change: extending the deploy module to support inheriting existing GitHub App installations instead of requiring fresh installs.
Description check	✅ Passed	The description provides comprehensive context about the changes, including the phase, summary of functionality, fallback behavior, gate evidence, user-visible changes, and rollback instructions, all directly related to the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/github-installation-phase5-cli

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codeant-ai]

Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI.

[agent-relay-code]

Fixed one issue in the PR’s GitHub installation flow: reconcile/join now re-resolves workspaceToken during polling instead of reusing the initial token, matching the existing OAuth status polling behavior. Fix is in connect.ts and connect.ts.

Added a regression test proving reconcile and join use the refreshed token after the sleep/poll boundary: connect.test.ts.

Validation run:
corepack pnpm --filter @agentworkforce/deploy test
Result: 179 tests passed.

Addressed comments

• gemini-code-assist[bot]: quota-limit warning only; no code finding to fix.
• codeant-ai[bot]: trial-limit warning only; no code finding to fix.
• coderabbitai[bot]: initial “processing” comment only; no review comments were present on the PR, and the current CodeRabbit status is success.
• cubic · AI code reviewer: neutral quota/line-limit check only; no annotations or code findings to fix.
• github-actions: Node.js 20 action deprecation warning in workflow metadata; invalid for this PR because the PR does not touch workflow files and the warning is unrelated to the changed deploy resolver.

[codeant-ai]

Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI.

[agent-relay-code]

Fixed a real issue in the GitHub installation fallback path: after OAuth polling, the second connect-session request now resolves the latest workspace token instead of reusing the pre-OAuth token. Added a regression test covering the fallback install flow and auth header sequence.

Addressed comments

• No bot or reviewer comments were present in the provided .workforce artifacts, so there were no external review threads to validate or apply.

Verification:

• Ran corepack pnpm install
• Built required workspace deps for local test resolution
• Ran corepack pnpm --dir packages/deploy test successfully: 180 tests passed

Changed:

• packages/deploy/src/connect.ts
• packages/deploy/src/connect.test.ts

I am not printing READY because GitHub-side CI and mergeability were not available to verify in this sandbox.

[agent-relay-code]

Fixed a real regression in the PR’s GitHub installation fallback path: after OAuth/reconcile polling refreshes the workspace token, the fresh install-session fallback now re-resolves the token instead of reusing the stale initial token. Fixed in packages/deploy/src/connect.ts:250.

Added a regression test covering the no-inheritable-org fallback and verifying the OAuth session, reconcile request, fallback install session, and final status poll all use the expected refreshed token sequence. Test added in packages/deploy/src/connect.test.ts:636.

Validation run:
corepack pnpm --filter @agentworkforce/deploy test passed: 180 tests.
corepack pnpm --filter @agentworkforce/deploy build passed.

Addressed comments

• gemini-code-assist[bot]: quota-limit warning only; no code finding to fix.
• codeant-ai[bot] at initial PR creation: trial-limit warning only; no code finding to fix.
• coderabbitai[bot]: reported no actionable comments; docstring coverage was a warning, not tied to a specific PR breakage, so no code change was made for it.
• codeant-ai[bot] after synchronize: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot]: raised stale-token handling for reconcile/join; current checkout already fixed that in packages/deploy/src/connect.ts:460, and I fixed the remaining validated stale-token fallback case in packages/deploy/src/connect.ts:250 with coverage in packages/deploy/src/connect.test.ts:636.

I did not print READY because GitHub currently reports PR #217 as closed and its latest head SHA differs from the checkout context, so mergeability/readiness cannot be truthfully confirmed from this run.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed the PR diff and changed files. I made no source edits in this run because the current checkout already contains the token-refresh fixes raised in prior review notes, and I did not reproduce additional breakage in the changed GitHub installation flow.

Validation run locally:
corepack pnpm install
corepack pnpm --filter @agentworkforce/persona-kit build
corepack pnpm --filter @agentworkforce/deploy test passed: 180 tests
corepack pnpm --filter @agentworkforce/deploy build passed

GitHub API currently reports PR #217 is already merged/closed, so I am not printing READY.

Addressed comments

• gemini-code-assist[bot] issue comment 4653962050: quota-limit warning only; no code finding to fix.
• codeant-ai[bot] issue comment 4653962089: trial-limit warning only; no code finding to fix.
• coderabbitai[bot] issue comment 4653963561: rate-limit/docstring-coverage warning only; no actionable inline review comments. Docstring coverage warning was not tied to demonstrated PR breakage, so no code change.
• codeant-ai[bot] issue comment 4654013022: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] issue comment 4654013080: stale-token reconcile/join concern is already handled in current checkout at connect.ts and covered at connect.test.ts.
• codeant-ai[bot] issue comment 4654071720: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] issue comment 4654071798: fallback install-session stale-token concern is already handled in current checkout at connect.ts and covered at connect.test.ts.
• agent-relay-code[bot] issue comment 4654087372: summarizes the same already-present fallback-token fix at connect.ts with coverage at connect.test.ts.
• cubic · AI code reviewer check run: neutral review-limit result with zero annotations; no code finding to fix.
• github-actions check annotation: Node.js 20 action deprecation warning in .github; invalid for this PR because the PR changed only deploy connector files, not workflow configuration.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #217 against the current checkout. I did not make source edits because the current code already contains the validated token-refresh fixes and I did not reproduce additional breakage in the PR-changed flow.

Validation run:

• corepack pnpm install
• corepack pnpm --filter @agentworkforce/persona-kit build
• corepack pnpm --filter @agentworkforce/deploy test passed: 180 tests
• corepack pnpm --filter @agentworkforce/deploy build passed

Addressed comments

• gemini-code-assist[bot] issue comment 4653962050: quota-limit warning only; no code finding to fix.
• codeant-ai[bot] issue comment 4653962089: trial-limit warning only; no code finding to fix.
• coderabbitai[bot] issue comment 4653963561: rate-limit/docstring-coverage warning only; no actionable inline finding. The docstring warning was not tied to demonstrated PR breakage.
• codeant-ai[bot] issue comment 4654013022: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] issue comment 4654013080: stale-token concern for reconcile/join is already handled in current checkout at packages/deploy/src/connect.ts:461 and packages/deploy/src/connect.ts:470, covered by packages/deploy/src/connect.test.ts:579.
• codeant-ai[bot] issue comment 4654071720: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] issue comment 4654071798: fallback install-session stale-token concern is already handled in current checkout at packages/deploy/src/connect.ts:250, covered by packages/deploy/src/connect.test.ts:636.
• agent-relay-code[bot] issue comment 4654087372: summary of the same already-present fallback-token fix at packages/deploy/src/connect.ts:250, covered by packages/deploy/src/connect.test.ts:636.
• agent-relay-code[bot] issue comment 4654141707: review-only summary; current checkout still matches that assessment, with no additional breakage reproduced.
• cubic · AI code reviewer check run: neutral review-limit result with zero annotations; no code finding to fix.
• github-actions check annotation: Node.js 20 action deprecation warning in .github:2; invalid for this PR scope because the PR changed deploy connector files, not workflow configuration.

I am not printing READY because GitHub currently reports PR #217 as closed and merged, with mergeability unknown, and the status API still lists pending CodeRabbit statuses for this head.

[agent-relay-code]

pr-reviewer could not complete review for #217 in AgentWorkforce/workforce.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

pr-reviewer could not complete review for #217 in AgentWorkforce/workforce.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

Reviewed the PR diff and changed files. I made no source edits because the current checkout already contains the token-refresh fixes raised by prior bot comments, and I did not reproduce additional breakage in the PR-changed flow.

Verification:

• corepack pnpm install
• corepack pnpm --filter @agentworkforce/persona-kit build
• corepack pnpm --filter @agentworkforce/deploy build
• corepack pnpm --filter @agentworkforce/deploy test passed: 180 tests

GitHub reports PR #217 as closed and merged, so I am not printing READY.

Addressed comments

• gemini-code-assist[bot] comment 4653962050: quota-limit warning only; no code finding to fix.
• codeant-ai[bot] comment 4653962089: trial-limit warning only; no code finding to fix.
• coderabbitai[bot] comment 4653963561: rate-limit/docstring-coverage warning only; invalid because no deploy build/test failure or PR-specific missing-docstring breakage was reproduced.
• codeant-ai[bot] comment 4654013022: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] comment 4654013080: stale-token concern for reconcile/join is already handled in packages/deploy/src/connect.ts:461 and packages/deploy/src/connect.ts:470, covered by packages/deploy/src/connect.test.ts:579.
• codeant-ai[bot] comment 4654071720: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] comment 4654071798: fallback install-session stale-token concern is already handled in packages/deploy/src/connect.ts:250, covered by packages/deploy/src/connect.test.ts:636.
• agent-relay-code[bot] comment 4654087372: same fallback-token fix is already present in packages/deploy/src/connect.ts:250, covered by packages/deploy/src/connect.test.ts:636.
• agent-relay-code[bot] comment 4654141707: review-only summary; no additional current-checkout breakage reproduced.
• agent-relay-code[bot] comment 4654198919: review-only summary; current checkout still matches that assessment.
• agent-relay-code[bot] comment 4654231017: harness/operator failure notice only; this run completed local review and verification.
• agent-relay-code[bot] comment 4654233596: duplicate harness/operator failure notice only; this run completed local review and verification.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Reviewed PR #217 against the current checkout. I made no source edits: the previously raised token-refresh issues are already fixed in the checked-out code, and I did not reproduce additional breakage in the changed GitHub installation flow.

Verification run:
corepack pnpm --dir packages/deploy test passed, 180 tests.

GitHub API shows PR #217 is already closed and merged, so I am not printing READY.

Addressed comments

• gemini-code-assist[bot] comment 4653962050: quota-limit warning only; no code finding to fix.
• codeant-ai[bot] comment 4653962089: trial-limit warning only; no code finding to fix.
• coderabbitai[bot] comment 4653963561: rate-limit/docstring-coverage warning only; invalid for this PR because no deploy connector breakage or required missing-docstring failure was reproduced.
• codeant-ai[bot] comment 4654013022: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] comment 4654013080: stale reconcile/join token concern is already handled in packages/deploy/src/connect.ts:461 and packages/deploy/src/connect.ts:470, covered by packages/deploy/src/connect.test.ts:579.
• codeant-ai[bot] comment 4654071720: duplicate trial-limit warning only; no code finding to fix.
• agent-relay-code[bot] comment 4654071798: fallback install-session stale-token concern is already handled in packages/deploy/src/connect.ts:250, covered by packages/deploy/src/connect.test.ts:636.
• agent-relay-code[bot] comment 4654087372: same fallback-token fix is already present in packages/deploy/src/connect.ts:250, covered by packages/deploy/src/connect.test.ts:636.
• agent-relay-code[bot] comment 4654141707: review-only summary; no additional current-checkout breakage reproduced.
• agent-relay-code[bot] comment 4654198919: review-only summary; current checkout still matches that assessment.
• agent-relay-code[bot] comment 4654231017: harness/operator failure notice only; this run completed local review and verification.
• agent-relay-code[bot] comment 4654233596: duplicate harness/operator failure notice only; this run completed local review and verification.
• agent-relay-code[bot] comment 4654324406: prior review summary; current checkout still contains the referenced fixes and deploy package tests pass.