Spec: Forge Provider

Issue: MAR-39
Date: 2026-04-23
Status: In Review

Current implementation

shippercli/provider-forge is a Composer plugin built around the official laravel/forge-sdk v4 API v2 client. It is intentionally partial: it resolves or creates a site, triggers deployment, and protects cleanup with ownership tags. It provisions configured databases, environment variables, queue workers, scheduled jobs, certificates, and application logs through the Forge API v2 client. Owned preview sites can be enumerated and removed by the core orphan cleanup flow. Deployment rollback, server lifecycle, and automatic cleanup of server-level databases remain outside this provider contract.

Component	Responsibility
`ForgeProvider`	Validate configuration, plan, apply, and destroy
`ForgeClientInterface`	Injectable provider operation boundary
`ForgeApiClient`	Forge SDK v4/API v2 adapter
`ForgeProviderTest`	Capability, deployment, and ownership regression tests

Configuration

The provider requires:

api_token
organization_slug
server_id

The optional ownership_tag defaults to shipper-managed.

Supported behavior

Find a site by its configured domain on the selected server.
Create a PHP site when no matching site exists.
Trigger deployment through the Forge API v2 SDK.
Refuse destruction unless the returned site contains the ownership tag.
Apply configured databases, environment variables, workers, scheduled jobs, and certificates before deployment.
Enumerate and remove only owned preview sites during orphan cleanup.

Forge API v2 removed Git repository mutation endpoints. The site source must be configured in Forge before Shipper triggers deployment; the provider must not emulate the removed API v1 operation.

Capability state

Capability	State	Limitation
App deployment	Partial	Source setup is a Forge-side prerequisite.
Domain management	Supported	Site domain resolution/creation is supported.
SSL, databases, environment	Supported	Resources are applied through Forge API v2.
PHP, NGINX, redirects, network rules, aliases	Unsupported	The current Forge API v2 provider does not claim these mutations.
Workers, cron, observability	Supported	Existing resources are reused by name or command.
Rollback	Unsupported	Forge API v2 exposes deployment history but no safe rollback mutation.
Server lifecycle	Unsupported	Server lifecycle is not part of the merged provider contract.
Previews	Partial	Owned preview sites participate in orphan cleanup; database ownership is not exposed safely by Forge API v2.

Safety requirements

API v2 credentials and organization scope must be explicit.
A missing site ID or API exception fails the operation.
Destroy is idempotent for a missing site.
Destroy refuses an untagged site.
No provider operation may report success without an observable Forge API operation.