Attach to an existing app

A provider is one specific environment of a provider product your team runs. Attaching points one existing Laravel Cloud environment or Laravel Forge site at that provider, creates a per-app credential there, writes connection variables to the consumer, and opens a client-install pull request.

Attaching is available to team Owners and Admins, and it is free.

Prepare the provider

Before attaching an application:

1. Install or adopt the provider product.
2. Claim ownership of that provider deployment in Scalpels.
3. Enable its credential API if the connected-apps screen says it is off.
4. Connect GitHub and grant the Scalpels App access to the consumer repository.
5. Connect Laravel Cloud or Laravel Forge for the consumer application.

Claiming ownership, enabling the credential API and attaching are all free, including to an Experimental provider.

Choose an application

Open the Cloud or Forge tab on the dashboard and select Check again when the inventory is stale or missing. Choose Connect beside the environment or site you want to attach.

Scalpels re-checks that the target still exists in the connected hosting account immediately before writing. It also checks the provider's credential index rather than treating a Scalpels database row as proof that a credential can be minted.

What is written

The real provider URL, newly minted token, any fixed recipe switches, and BFC_CLIENT_IDENTITY — the id of the connection Scalpels recorded — are written into the selected Cloud environment. For Forge, the same keys are merged through the whole-file read-merge-write process described in Connect Laravel Forge.

The pull request changes only files required by the provider recipe:

• composer.json receives the client packages;
• .env.example receives the variable names, with the token left blank;
• .gitignore receives any product-owned paths.

The branch is named scalpels/connect-{product}. The pull request is requested as a draft and always carries [DRAFT] in its title. Scalpels cannot regenerate composer.lock, so check out the branch, run the package-specific composer update command shown in the pull request, commit the lock file, then review and merge it. Scalpels never merges it for you.

Refusals and repairs

No credential or environment change is made when Scalpels refuses before the write. Common messages mean:

• No record yet: select Check again, then use the refreshed row.
• Environment or site is gone: the connected account did not confirm the target.
• Cannot be connected from what we can see: the target is the provider itself, already reporting, or its state could not be determined.
• Already reports elsewhere: disconnect it from the other provider before repointing it.
• Already being connected: wait for that attempt to finish and check again.
• Ownership required: claim the provider deployment first.
• Credential API not enabled: enable it and retry.
• GitHub required or repository unreadable: connect GitHub or grant the App access to that repository.
• Environment file could not be read safely: correct the named Forge .env problem; Scalpels wrote nothing.

Credential already issued / repair required means the provider already has the deterministic credential name, either because Scalpels has an attribution row or because the provider's own index reports it. The plaintext credential cannot be read back, and Scalpels will not issue a second credential over the first.

Check the connected-apps list or Forge tab to see whether the provider has heard from the consumer. If it has not, remove the named credential on the provider and connect again. When a local attribution exists, it remains because it is the only durable record of which provider the consumer was pointed at.