Laravel Harbor Laravel Package

Product Decisions This Supports

• Build vs. buy for preview environments. Harbor turns "ephemeral per-PR environments" from a bespoke CI scripting project into a configuration surface. The v2.1.0 release removes the main reason teams hand-roll this glue: deploy-key generation, Git-provider registration, PR/MR commenting, and teardown of the key on deletion are now handled inside the package.
• Review-app capability on the roadmap. If stakeholder review, designer QA, or PM sign-off currently happens on a shared staging server, per-PR environments become a shippable feature rather than a platform-team side quest. Each pull request gets an isolated, addressable URL that can be shared outside engineering.
• Git-host standardization is no longer a locked-in decision. The release deliberately splits FORGE_GIT_PROVIDER (how Forge clones) from FORGE_GIT_API_PROVIDER (which API Harbor uses for deploy keys and comments). A PM can approve adoption for a GitHub.com shop today and still support an acquired team on self-hosted GitLab tomorrow without re-platforming the workflow.
• Vendor and cost modeling. Environments are Forge sites, so spend scales with concurrent open PRs, not headcount — a tractable variable to forecast and cap.
• Air-gapped / restricted-network viability. FORGE_DEPLOY_KEY_PUBLIC / FORGE_DEPLOY_KEY_PRIVATE allow bring-your-own keypairs when Harbor cannot reach the Git API, which unlocks adoption in network-restricted environments that would otherwise be a hard no.
• Announcement comments as a communication channel. Preview links now post to GitLab merge requests as well as GitHub PRs, which supports decisions about where review conversation lives — the PR/MR thread rather than Slack or email.

When to Consider This Package

Adopt when:

• The application is Laravel/PHP and is provisioned through Laravel Forge.
• Delivery is pull-request-driven and reviewers need a running environment, not just a diff.
• A shared staging environment is becoming a contention point (merge queues, "who's using staging?").
• You want preview environments without owning CI YAML that calls the Forge API, mints SSH keys, and comments on PRs.
• You are on GitHub.com, GitLab.com, self-hosted GitLab, Bitbucket, or a custom Git URL — all covered as of v2.1.0.

Look elsewhere when:

• You are not on Forge (Vapor, Kubernetes, Ploi, Envoyer) or not on Laravel — the value is almost entirely Forge integration.
• You need preview environments that are not 1:1 with a pull request (per-branch, per-customer, per-feature-flag).
• You are below PHP 8.2; v2 requires 8.2+, so this is a hard gate, including the laravel-test-runner image version in CI.
• Your Git host requires human approval for key registration and you cannot use a token — BYO keypair is the mitigation, but it makes provisioning partly manual.

Adoption risks to plan for (not blockers):

• Token scopes. The default GITHUB_TOKEN in Actions cannot manage deploy keys. A GitHub App needs Repository → Administration: Read & write; a PAT needs repo. Decide this before rollout or provisioning stops with a 403.
• Concurrency. Two runs for the same PR can race and fail with site: The site must be installed before it can be deployed. Add a per-PR concurrency group to both provision and teardown jobs as part of the initial setup, not as a follow-up ticket.
• Deprecation debt. FORGE_GITHUB_DEPLOY_KEY still works but warns and is slated for removal in a future major. Rename to FORGE_DEPLOY_KEY now while it is a one-line diff.

How to Pitch It (Stakeholders)

For executives: This is a low-cost capability upgrade on infrastructure we already pay for. It gives every pull request its own throwaway environment, so reviewers, QA, and product can see work running before it merges — no shared staging bottleneck and no custom tooling to maintain. The v2.1.0 release is the maturity milestone: multi-provider Git support, automatic deploy-key lifecycle management, and preview links posted directly on PRs and merge requests.

For engineering: Harbor owns the parts of preview environments that are tedious and easy to get wrong. This release fixes the v2 deploy-key regression, decouples the clone provider from the Git API provider so self-hosted hosts are supported, validates git_provider up front instead of failing mid-provision, and cleans up deploy keys on teardown. Error messages are actionable — a 403 names the exact missing scope. Upgrade cost is one env-var rename plus a PHP 8.2 floor; adding a per-PR concurrency group is strongly recommended to eliminate a known race.

Ask: Approve a timeboxed pilot on one team — enable FORGE_DEPLOY_KEY, set the Git API provider and token, add the concurrency group, and measure review turnaround and staging contention over a sprint before committing to org-wide rollout.