Veyoze Laravel Package

Product Decisions This Supports

• Preview environments per pull request as a product capability. Harbor automates the create-deploy-comment-teardown lifecycle of an ephemeral Forge site for every PR. This is the lever for shortening the feedback loop between "code merged" and "stakeholder/QA sign-off," and for removing shared-staging as a contention point across squads.
• Build vs. buy for preview infrastructure. The v2.1.0 release reframes this decision: first-class GitHub and GitLab providers (GitLab.com, self-hosted GitLab, custom git URLs) mean the same tool now covers the two dominant SCM estates, so a single adoption decision can serve multiple teams instead of forking per-VCS tooling.
• Vendor and hosting strategy. Harbor sits on top of Laravel Forge. Adopting it is implicitly a decision to keep Forge as the provisioning layer rather than migrate to Laravel Cloud, Vercel-style previews, or hand-rolled CI scripts. Useful for roadmap conversations about platform consolidation and lock-in.
• Enterprise / regulated-environment readiness. Bring-your-own keypair (FORGE_DEPLOY_KEY_PUBLIC / FORGE_DEPLOY_KEY_PRIVATE) and GIT_API_URL for self-hosted instances mean Harbor can be adopted where the Git API is not reachable from CI (air-gapped, restricted egress, self-managed GitLab). That converts a previously hard "no" into a supported configuration.
• Prioritization of internal developer experience (DevEx) work. Reliability items in this release — deploy-key provisioning on Forge's current API, early validation of git_provider, the per-PR concurrency guidance — are the kind of toil that erodes trust in internal tooling. This is a concrete backlog item to point at when arguing for platform-team investment.
• Migration and upgrade planning. The FORGE_GITHUB_DEPLOY_KEY → FORGE_DEPLOY_KEY deprecation (alias retained, removal in a future major) and the PHP 8.2+ requirement are roadmap inputs: schedule the rename, confirm runtime versions, and budget for the eventual major.
• Adoption funnel design. Clear, actionable failure messages (403 with the exact missing GitHub App permission, "no Git API configured" with the public key printed for manual registration) reduce the support burden of rolling this out — relevant to how you sequence a pilot vs. a broad rollout.

When to Consider This Package

Consider adopting when:

• You run Laravel applications on Laravel Forge and want per-PR environments without building the orchestration yourself.
• Your team is on GitHub or GitLab — including self-hosted GitLab — and wants PR/MR comments carrying the preview URL. Prior to this release, GitLab was a genuine gap; that objection is now closed.
• You want an existing, maintained package rather than owning a bespoke CI script that creates/destroys Forge sites. The cost of the script is not the writing; it is the pager rotation when Forge's API shifts (exactly the failure this release fixes for deploy keys).
• Your environment restricts outbound access to the Git API. Use the documented bring-your-own-keypath mode and register keys manually or via an internal process.
• You need preview environments as a QA/UAT and stakeholder-review surface, not as a production hosting decision.

Look elsewhere when:

• You are not on Forge (or are actively migrating off it). Harbor is a Forge orchestrator; its value is coupled to that choice.
• You are on PHP < 8.2 — v2 requires 8.2+, and the documented CI container example moved to :8.3. Check your laravel-test-runner (or equivalent) image before committing.
• Your preview environments need persistent state, seeded databases, or long-lived shared services. Harbor's model is ephemeral per-PR sites; anything stateful becomes your problem.
• Cost-per-PR is unmanaged. Each preview site consumes real Forge/server resources. Without teardown discipline (closed PRs, stale branches, the per-PR concurrency group recommended in the release notes) you will accrue orphaned sites and spend.

Rollout caveats to plan for:

• Add a per-PR concurrency group to both provision and teardown jobs. Without it, rapid successive pushes or PR reopen races two runs against the same site and one fails with The site must be installed before it can be deployed. This is a documentation fix, not a code fix — it needs to land in your workflow templates, not just in someone's reading.
• Deploy-key registration requires real Git API permissions. The default GITHUB_TOKEN in Actions cannot manage deploy keys; GitHub App tokens need Administration: Read & write, PATs need repo scope. Budget a short permissions review with security before rollout.
• FORGE_GIT_PROVIDER is now strictly validated (github, gitlab, gitlab-custom, bitbucket, custom), and custom additionally requires FORGE_GIT_REPOSITORY_URL. Typos that previously slipped through will now fail early — good, but expect a few broken pipelines on first upgrade.

How to Pitch It (Stakeholders)

For executives — one paragraph: Harbor lets every pull request get its own disposable, fully deployed copy of the application, created and torn down automatically. That compresses the review cycle: product, design, and QA can click a real URL instead of waiting for a shared staging slot or running the branch locally. The v2.1.0 release materially widens who can use it — GitLab (cloud and self-hosted) is now a first-class provider alongside GitHub, and the deploy-key path that broke in v2 is fixed with no action required beyond upgrading. It lowers the cost of shipping frequently without adding headcount to release management.

For engineering leadership — the argument: This is a buy-vs-build call we should make deliberately. The alternative is a homegrown CI script that calls the Forge API; the real cost there is not writing it, it is owning it when the API changes. That is precisely what happened here — deploy-key creation broke against Forge's current API in v2 and this release fixes it, and the fix is "upgrade." Adopting a maintained package transfers that maintenance risk off our team. The upgrade itself is low-risk: existing GitHub workflows and pre-v2 custom setups keep working unchanged, and the only mandatory code-adjacent change is renaming one env var (FORGE_GITHUB_DEPLOY_KEY → FORGE_DEPLOY_KEY), which is currently a warning, not a break.

For engineering — what to actually do:

1. Confirm PHP 8.2+ across workflows; update any laravel-test-runner pin from :8.1 to :8.3.
2. Rename FORGE_GITHUB_DEPLOY_KEY to FORGE_DEPLOY_KEY now, while the alias still works.
3. Add concurrency: group: harbor-${{ github.event.pull_request.number }}, cancel-in-progress: false to both provision and teardown jobs. This is the single highest-value change in the release notes for reducing flaky runs.
4. Audit GIT_TOKEN permissions: GitHub App needs Administration: Read & write (and the installation must accept the updated permissions); PAT needs repo scope. GITHUB_TOKEN is not sufficient.
5. If you run self-hosted GitLab, set FORGE_GIT_API_PROVIDER=gitlab-custom and GIT_API_URL=https://<host>/api/v4; this also re-enables MR announcement comments (GIT_ISSUE_NUMBER = the MR iid).
6. If your CI cannot reach your Git API at all, use FORGE_DEPLOY_KEY_PUBLIC / FORGE_DEPLOY_KEY_PRIVATE and register the key out-of-band — this is a supported path and the warnings tell you exactly what was skipped.