Add Bitbucket integration for auth, repo access, sandbox git flow, and PR creation by Abhinandan-Khurana · Pull Request #177 · ColeMurray/background-agents

Abhinandan-Khurana · 2026-02-21T12:29:40Z

Summary
This PR adds end-to-end Bitbucket support to Background Agents by extending the existing source-control abstraction and session pipeline.

What’s included

Added BitbucketSourceControlProvider and factory wiring for repo lookup, push auth/spec, and PR creation.
Added Bitbucket OAuth flow in web auth and provider-neutral SCM token/session fields across web + control-plane.
Added per-session vcsProvider persistence and provider-aware runtime resolution in Session DO.
Added Bitbucket repo listing and repo validation using OAuth token fallback.
Updated sandbox creation/restore and entrypoint git sync to use provider-neutral VCS_* credentials.
Updated docs, env examples, and Terraform config for Bitbucket variables/secrets.
Added security fix to avoid putting OAuth access tokens in URL query params during userinfo.

Validation

Typecheck passed (web, control-plane, workspace)
Control-plane tests passed
Web tests passed
Modal tests passed

greptile-apps · 2026-02-21T12:32:24Z

Greptile Summary

Comprehensive Bitbucket integration PR that extends the existing GitHub-only codebase to support multiple VCS providers with provider-neutral abstractions. Implements OAuth flow, token management, sandbox git operations, and PR creation for Bitbucket alongside existing GitHub support.

Major changes:

Added BitbucketSourceControlProvider implementing the same interface as GitHub provider with repository access, PR creation, and push auth generation
Extended session and participant schemas with vcs_provider, scm_provider, and provider-neutral scm_* token fields while maintaining backward compatibility with legacy github_* fields
Updated sandbox entrypoint to use provider-neutral VCS_* environment variables for git clone/push operations
Added Bitbucket OAuth flow in web auth with security fix removing token from URL query params
Extended control-plane routing to resolve provider per-session and support both bot credentials and user OAuth tokens

Architecture:

Uses factory pattern for provider selection with runtime resolution from session state
Maintains backward compatibility by defaulting to GitHub when vcs_provider not set
Schema migrations (19-27) add new columns with safe defaults for existing sessions
Sandbox manager passes provider-specific credentials via environment variables based on vcs_provider

Test coverage:

Unit tests added for Bitbucket provider (repository fetch, PR creation, push spec building)
Existing tests updated to include provider context
All reported test suites passing

_{Last reviewed commit: f07cec5}

ColeMurray · 2026-02-21T15:15:31Z

packages/web/src/components/sidebar-layout.tsx

+            onClick={() => signIn("bitbucket")}
+            className="flex items-center gap-2 bg-secondary text-secondary-foreground px-6 py-3 font-medium hover:opacity-90 transition"
+          >
+            Sign in with Bitbucket


[Automated Review] Both sign-in buttons are rendered unconditionally, but the auth providers in auth.ts are conditionally registered based on env vars (BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET). Clicking "Sign in with Bitbucket" when no Bitbucket OAuth consumer is configured will cause a NextAuth runtime error.

Gate the Bitbucket button on provider availability (e.g., expose configured providers via the session or a server-side check) so it only appears when Bitbucket OAuth is actually configured.

ColeMurray · 2026-02-21T15:15:31Z

terraform/environments/production/variables.tf

-    condition     = var.enable_github_bot == false || (length(var.github_webhook_secret) > 0 && length(var.github_bot_username) > 0)
-    error_message = "When enable_github_bot is true, github_webhook_secret and github_bot_username must be non-empty."
-  }
 }


[Automated Review] The validation blocks for enable_github_bot and enable_linear_bot (which enforced that required secrets are non-empty when the bot is enabled) have been removed. This weakens deploy-time validation and is unrelated to Bitbucket support.

Please revert these deletions or, if intentional, justify in the PR description and split into a separate commit.

ColeMurray · 2026-02-21T15:18:45Z

packages/shared/src/types/index.ts

@@ -207,7 +208,7 @@ export interface ParticipantPresence {

 // Repository types for GitHub App installation
 export interface InstallationRepository {


[Automated Review] Widening id from number to string | number is a breaking change to a shared interface consumed by multiple packages. Any downstream code that assumes id is a number (strict equality checks, arithmetic, database schemas expecting INTEGER) will break silently or fail at runtime for Bitbucket repos where id is a UUID string like "{123}".

The use-repos.ts hook mirrors this change, so the break propagates to the web client as well.

Recommendation: Keep id: number and add a separate optional providerRepoId?: string field for Bitbucket's UUID identifier. This avoids forcing every consumer to handle a union type for what was previously a simple numeric ID.

ColeMurray · 2026-02-21T15:18:45Z

packages/control-plane/src/routes/shared.ts

+import { resolveScmProviderFromEnv, type SourceControlProviderName } from "../source-control";
+
+function stableRepoIdFromFullName(fullName: string): number {
+  let hash = 0;


[Automated Review] This hash function has several problems:

Overflow bug: (hash * 31 + charCode) | 0 forces 32-bit signed int. When hash equals -2147483648 (valid 32-bit int), Math.abs(-2147483648) returns 2147483648 in JS, then + 1 gives 2147483649 — but in some edge cases Math.abs of the minimum 32-bit int is itself negative in engines that use 32-bit internally. This is fragile.

Collision risk: A 31-bit hash space (~2 billion values) makes collisions likely across repos. Since repoId is stored in D1 and used for session-to-repo association, a collision would silently associate sessions with the wrong repository.

Applied to GitHub path too: The fallback in resolveInstalledRepo (typeof repo.id === "number" ? repo.id : stableRepoIdFromFullName(...)) means this hash could be used for GitHub repos if repo.id comes through as a string for any reason — changing repoId values for existing sessions and orphaning them in the session index.

Recommendation: Use Bitbucket's UUID string directly as the repo identifier (see comment on InstallationRepository.id) rather than hashing it into a synthetic numeric ID.

ColeMurray · 2026-02-21T15:18:45Z

packages/control-plane/src/router.ts

+  const sessionScmProvider = body.vcsProvider ?? resolveDeploymentScmProvider(env);
+  const scmToken = body.scmToken ?? body.githubToken;
+
+  let repoId: number | null;


[Automated Review] repoId was previously number (always set by resolveInstalledRepo for GitHub). Changing it to number | null means null can now flow into the Session DO's upsertSession call and be stored as NULL in the repo_id SQLite column.

This changes the data model for sessions — any queries filtering or joining on repo_id (e.g., the D1 session index, repo secrets lookups) will silently miss these sessions. Existing code downstream likely assumes repo_id is always a valid integer.

Recommendation: Ensure resolveInstalledRepo always returns a non-null repoId (even for Bitbucket), or add explicit null handling in all downstream consumers before this goes in.

ColeMurray · 2026-02-21T15:18:45Z

packages/control-plane/src/router.ts

-      return withCorsAndTraceHeaders(response, ctx);
-    }
-
+    resolveDeploymentScmProvider(env);


[Automated Review] The entire 501 guard for unimplemented SCM providers has been removed. Previously, setting SCM_PROVIDER=bitbucket without a working implementation would return a clear 501 Not Implemented on all non-public routes. Now requests proceed and will fail with less obvious errors deeper in the stack if Bitbucket credentials are missing or misconfigured.

Recommendation: Replace the old guard with credential validation — e.g., if provider === "bitbucket" and none of BITBUCKET_BOT_USERNAME, BITBUCKET_BOT_APP_PASSWORD, BITBUCKET_CLIENT_ID are set, return a clear error early rather than letting requests fail in auth/repo-resolution layers with confusing messages.

ColeMurray · 2026-02-21T15:19:06Z

packages/modal-infra/src/sandbox/bridge.py

 from websockets.exceptions import InvalidStatus

+try:
+    from websockets import State


[Automated Review] These changes are unrelated to Bitbucket and appear to be fixing a websockets library version compatibility issue. The ClientConnection type annotation changed to Any which weakens type safety.

Please split this into a separate commit/PR, and consider using a version-conditional type alias instead of Any to preserve type checking.

ColeMurray · 2026-02-21T15:19:06Z

.gitignore

 terraform/environments/production/terraform.tfstate*
 terraform/environments/production/.terraform*
+terraform/environments/production/terraform.tfvars.backup-*
+


[Automated Review] research.md and plan.md look like developer scratch files that should not be in the public repo's .gitignore. Consider removing these entries — they belong in a personal global gitignore (~/.gitignore_global) rather than the project-level ignore file.

ColeMurray · 2026-02-21T15:19:06Z

packages/shared/src/index.ts

 */

-export * from "./types";
+export * from "./types/index";


[Automated Review] This change from "./types" to "./types/index" is functionally equivalent but gratuitous — Node/TypeScript module resolution already resolves "./types" to "./types/index". The explicit /index suffix could cause issues with certain bundler caching or TypeScript project reference configurations. Please revert unless there's a specific reason for the change.

ColeMurray · 2026-02-21T15:20:15Z

packages/control-plane/src/session/participant-service.ts

+        const githubClientSecret = this.env.GITHUB_CLIENT_SECRET;
+        const refreshed = await refreshAccessToken(refreshToken, {
+          clientId: githubClientId as string,
+          clientSecret: githubClientSecret as string,


[Automated Review] refreshToken() now calls updateParticipantScmTokens() instead of updateParticipantTokens().

For existing GitHub sessions, this writes to scm_* columns AND conditionally to github_* columns (via the CASE WHEN ? = 'github' SQL). Existing participants have scm_provider defaulting to 'github' from the migration, but scm_refresh_token_encrypted will be null. The refreshToken() method reads from scm_refresh_token_encrypted ?? github_refresh_token_encrypted, which is fine for fallback, but after the first refresh it writes to scm_* columns — so the github_* columns will be updated via the CASE statement, which is correct.

However, the old updateParticipantTokens() method still exists — it's not clear if any other code path still calls it. If so, those callers would write to github_* columns only, causing the scm_* and github_* columns to drift out of sync. Please either remove updateParticipantTokens() if it's dead code, or document which callers use which method and why.

Prep for Bitbucket integration (PR #177). Refactor the sandbox manager and entrypoint to use VCS-provider-neutral env vars (VCS_HOST, VCS_CLONE_USERNAME, VCS_CLONE_TOKEN) derived from the deployment-level SCM_PROVIDER env var, so the sandbox pipeline works for any provider. - Rename SandboxConfig.github_app_token → clone_token - Rename restore_from_snapshot(github_app_token=) → clone_token= - Inject VCS_HOST/VCS_CLONE_USERNAME/VCS_CLONE_TOKEN in both create_sandbox() and restore_from_snapshot() - Gate GITHUB_APP_TOKEN/GITHUB_TOKEN on scm_provider == "github" - Add _build_repo_url() helper, replacing 3 inline URL constructions - Read VCS_* env vars in entrypoint with fallback to GITHUB_APP_TOKEN

## Summary Prep for Bitbucket integration (PR #177). Refactors the sandbox manager and entrypoint to use VCS-provider-neutral env vars derived from the deployment-level `SCM_PROVIDER` env var, so the sandbox pipeline works for any provider without hardcoding `github.com` or `x-access-token`. - **manager.py**: Rename `SandboxConfig.github_app_token` → `clone_token`, inject `VCS_HOST`/`VCS_CLONE_USERNAME`/`VCS_CLONE_TOKEN` in both `create_sandbox()` and `restore_from_snapshot()`, gate `GITHUB_APP_TOKEN`/`GITHUB_TOKEN` on `scm_provider == "github"` - **entrypoint.py**: Read VCS_* env vars (with fallback to `GITHUB_APP_TOKEN`), add `_build_repo_url()` helper replacing 3 inline URL constructions - **web_api.py**: Update 2 callers for renamed `clone_token` field **Prerequisite**: `SCM_PROVIDER` must be added to the `internal-api` Modal secret in Terraform before Bitbucket deployments work. Existing GitHub deployments are unaffected (defaults to `"github"`). ## Test plan - [x] All 154 tests pass (142 existing + 12 new) - [x] `ruff check` and `ruff format` clean - [ ] Verify GitHub deployment still works (default path, no `SCM_PROVIDER` needed) - [ ] After Terraform adds `SCM_PROVIDER=bitbucket`, verify Bitbucket clone URLs are correct

Abhinandan-Khurana added 7 commits February 21, 2026 17:45

add bitbucket source provider

b8848ee

store scm provider and tokens

2f6fd16

use bitbucket oauth for repo list

3ab64fb

add bitbucket web auth flow

c0c6451

pass vcs creds to sandbox

9e1e9fe

update docs and terraform config

12b7424

remove token in userinfo url

f07cec5

Abhinandan-Khurana mentioned this pull request Feb 21, 2026

🚀 Feature request: Bitbucket Integration Support #61

Open

5 tasks

ColeMurray reviewed Feb 21, 2026

View reviewed changes

ColeMurray mentioned this pull request Feb 22, 2026

refactor: VCS-neutral sandbox git operations #212

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add Bitbucket integration for auth, repo access, sandbox git flow, and PR creation#177

Add Bitbucket integration for auth, repo access, sandbox git flow, and PR creation#177
Abhinandan-Khurana wants to merge 7 commits intoColeMurray:mainfrom
Abhinandan-Khurana:bitbucket-dev

Abhinandan-Khurana commented Feb 21, 2026

Uh oh!

greptile-apps bot commented Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

ColeMurray Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -207,7 +208,7 @@ export interface ParticipantPresence {

		// Repository types for GitHub App installation
		export interface InstallationRepository {

Comments

Conversation

Abhinandan-Khurana commented Feb 21, 2026

Uh oh!

greptile-apps bot commented Feb 21, 2026

Greptile Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants