Projects and services

This workflow requires core 1.21.0 and CLI/MCP 1.19.1 or later. Server-side merging is disabled by default until deployment qualification; a ready preview does not enable apply.

A project represents a system investigated together. Services represent its applications or processes, each with repository context and environments. Site, App, API and Worker can belong to one project. No Product/Group layer or Business tier is required. Existing sharing and automation plan rules still apply.

Inspect services

debugbundle services list --project-id PROJECT_ID --json
debugbundle services get SERVICE_DEFINITION_ID --project-id PROJECT_ID --json
debugbundle services create --project-id PROJECT_ID --name Site --repository-url https://github.com/example/site --repository-root apps/site --json
debugbundle services update SERVICE_DEFINITION_ID --project-id PROJECT_ID --description "Public site" --json

Logical service_definition_id is stable across environments. Existing environment-specific service_id keeps its original meaning. List accepts --limit (1–200) and --cursor; follow next_cursor until null. Metadata updates retain original SDK input names. --clear-repository restores the current project default; moving a service during consolidation preserves its original default, including a previously absent repository. Repository metadata never grants access to a repository or edits it. GitHub dispatch can use only an explicitly registered repository inside this project's retained origins and an active same-account installation. A service URL cannot select an unrelated project's connection. Existing repository binding endpoints still accept the original project ID for that binding; current canonical owner/admin access is required. Updating it preserves its rules, while removing it removes only that origin's binding/rules.

The older debugbundle services --project-id PROJECT_ID command still lists environment instances. Its --limit and additive --offset paginate up to 100 instances per page. Existing response formats are retained.

Consolidate existing projects

The owner chooses an existing destination. Initially all selected projects must have the same account/owner and compatible effective access and settings. Preview reports conflicts; it does not silently change recipients, privacy, retention, consent, sharing or automation policy. Resolve conflicts explicitly and preview again. Preview does not mint credentials or move data.

debugbundle project merge preview --target TARGET_ID --sources SITE_ID,API_ID --json > inventory.json
# Review suggested_service_mappings; save the chosen array as mappings.json.
debugbundle project merge preview --target TARGET_ID --sources SITE_ID,API_ID --mapping-file mappings.json --json > checked-plan.json
debugbundle project merge apply --plan-file checked-plan.json --idempotency-key system-consolidation-1 --json
debugbundle project merge status --idempotency-key system-consolidation-1 --json
debugbundle project merge verify OPERATION_ID --json

All commands support non-interactive agent use and ordinary member authentication. Suggestions are deterministic; mappings remain explicit. Apply checks the exact preview digest and current permissions inside the cutover transaction. Reuse the same idempotency key and exact request after a timeout; look up its status first. resume OPERATION_ID recovers eligible work. cancel OPERATION_ID is available before commit; it cannot undo a committed consolidation.

Existing evidence IDs, artifact bytes/keys, queued jobs, histories, credentials and their scopes remain valid. Old credentials do not gain access to newly imported origins. Normal project lists show canonical projects; project list --project-id LEGACY_ID resolves the retained original view using current access. Project-wide management through a legacy ID returns project_consolidated with the canonical ID. Existing token revocation remains available.

Adopt an authorised repository

A completed server operation includes a credential-free adoption_manifest. Server completion, repository adoption and deployed runtime verification are separate gates. The agent must have permission naming the repository/product and the edits. A DebugBundle merge does not authorise editing other products.

debugbundle project merge adopt preview --operation-id OPERATION_ID --workspace-root /absolute/authorised/repository --json > adoption-plan.json
debugbundle project merge adopt apply --plan-file adoption-plan.json --json

The helper checks cloud status/verification and previews semantic changes to the recognised local connection/profile files. It preserves credentials, retained runtime input names, custom profile data and caches, and rejects concurrent file changes or unsafe paths. Service/repository metadata is explicitly a receipt snapshot; inspect the current catalogue before any wider repository work. Unknown or ambiguous layouts require agent review. After applying these files, local_adoption remains pending_repository_checks and deployed_runtime remains pending. Run the repository's checks and separately authorised deployment and runtime verification before declaring those gates complete.

An interrupted helper may retain .debugbundle/adoption.lock. Confirm no adoption process is running before removing that lock and retrying the checked plan. A receipt superseded by another consolidation requires a new applicable operation. After a committed merge, use forward repair and a qualified compatible runtime rollback; returning to a binary unaware of origins and aliases is unsupported.