Laravel Harbor Laravel Package

Technical Evaluation

What this package is. Laravel Harbor is a developer-tooling package (CLI + laravel-harbor config) that provisions ephemeral preview environments per pull request on Laravel Forge, then tears them down. It is not a runtime dependency of the application; it lives in the CI workflow and holds Forge and Git API credentials. That framing matters more than any individual feature, because the blast radius of adopting or upgrading it is CI and infrastructure-adjacent, not production-adjacent.

Assessment of v2.1.0. This is a capability release with one genuine bug fix and two compatibility decisions, not a refactor:

• Deploy keys actually work again on Harbor v2. The prior failure was hard-blocking (public_deploy_key / private_deploy_key validation errors from Forge), meaning any team that needed private repo cloning could not use Harbor v2 at all. The fix is the correct shape: generate a keypair before site creation, register the public half with the Git host, hand both halves to Forge, and delete the key on teardown. Upgrade alone resolves it.
• Provider abstraction via FORGE_GIT_API_PROVIDER. This correctly separates "how Forge clones" from "which Git API Harbor calls for deploy keys and PR/MR comments." Defaulting the API provider to the clone provider, plus URL-based inference for github.com / gitlab.com, keeps the common case zero-config. Self-hosted GitLab is now covered, which is the main capability unlock for enterprise buyers.
• FORGE_DEPLOY_KEY supersedes FORGE_GITHUB_DEPLOY_KEY with an alias and a CI log warning. Managed, low-friction deprecation, but it is debt with a scheduled breaking change in the next major.
• Escape hatches and observability. FORGE_DEPLOY_KEY_PUBLIC / FORGE_DEPLOY_KEY_PRIVATE for environments Harbor cannot reach, and warning-level messages that print the public key when auto-registration is impossible. Good incident ergonomics.
• Validation tightened to github, gitlab, gitlab-custom, bitbucket, custom, with custom requiring FORGE_GIT_REPOSITORY_URL. Failing before the Forge call is the right fail-fast boundary.

Technical risks.

1. Credential scope escalation is the headline risk. Deploy-key registration requires a GitHub App permission of Administration: Read & write, or a PAT with repo scope. The default GITHUB_TOKEN in Actions cannot do this. A TPM should treat this as a security review item, not a CI config detail — the token Harbor holds is materially more powerful after v2.1.0 than before it, and it must be custodied accordingly (dedicated app, per-repo installation, rotation owner).
2. Private key handling. Harbor now generates and transmits a private key into Forge. That private key is a credential in CI logs' blast radius if it is ever echoed; the release notes' warning path intentionally prints only the public key, which is correct, but the BYO-keypath (FORGE_DEPLOY_KEY_PRIVATE) introduces a secret we now own.
3. Silent-degrade paths. When no Git API is configured, Harbor warns and continues: the site is created but the deploy key is not registered, and the PR comment is skipped. This is the right default for availability, but it means a green pipeline is not proof that preview-environment automation is fully working.
4. Race conditions remain a user-side responsibility. The release explicitly recommends per-PR concurrency groups. Without them, rapid pushes or PR reopen produce a hard failure (site must be installed before it can be deployed), plus orphaned or duplicate Forge sites.
5. bitbucket is accepted by validation but has no API provider. A typo-adjacent trap: config validates, deploy-key registration and comments silently degrade.

Key questions to resolve before adoption.

• Which Git host(s) are in scope — GitHub SaaS, GitLab SaaS, self-hosted GitLab — and is PR/MR commenting a requirement or a nice-to-have?
• Which credential type will we standardize on (GitHub App vs PAT), who owns it, and what is the rotation and offboarding procedure?
• Do we actually need deploy keys, or are the target repositories public/pre-cloned, letting us skip FORGE_DEPLOY_KEY entirely and avoid the scope escalation?
• What is the acceptable Forge cost ceiling per concurrent open PR, and do we need a label-gated provisioning rule?
• Is anyone currently on FORGE_GITHUB_DEPLOY_KEY (the alias works, but the warning will appear on every run)?

Integration Approach

Stack fit. Harbor assumes a Laravel app deployed via Forge, with CI on GitHub Actions or GitLab CI. v2.1.0 hard-requires PHP 8.2+, so runner images must move accordingly (the docs' kirschbaumdevelopment/laravel-test-runner:8.1 example must become :8.3). If our app is not on Forge, or preview environments are already handled by a platform-native mechanism, this package is not a candidate regardless of release quality. There is no production runtime coupling, no database migration, and no application code change — integration surface is entirely env vars plus workflow YAML.

Compatibility posture. Backward compatible by design: default GitHub setups and the pre-v2 "GitHub custom" combination (FORGE_GIT_PROVIDER=custom + FORGE_GITHUB_DEPLOY_KEY=true) keep working. The only forced change is the PHP 8.2+ floor. The FORGE_GITHUB_DEPLOY_KEY alias means we can adopt v2.1.0 without touching secrets, then rename on a deliberate timeline rather than under pressure.

Migration path (sequenced).

Sequencing note. Do step 5 before step 7. Concurrency is a one-line workflow change with outsized stability benefit, and shipping it late means the first wave of users experiences duplicate-site failures and blames the upgrade.

Operational Impact

Maintenance. Low ongoing effort, but non-zero. Two items carry forward: (a) the deprecated FORGE_GITHUB_DEPLOY_KEY will be removed in a future major, so schedule the rename now rather than at forced-upgrade time; (b) PHP minor-version currency is now a hard dependency, so the runner image version becomes part of the package's maintenance envelope. Pin to a minor range and review on each release; Harbor's changelog is small and readable, which keeps upgrade cost near zero.

Support model. Almost every failure this release can produce is credential configuration, and the messages are unusually good — they name the missing permission and, for the token case, name the exact GitHub App permission and PAT scope. That is a genuine support-cost reduction and should be documented verbatim in the internal runbook rather than paraphrased. The single highest-value runbook entry: "403 while registering deploy key" → token lacks deploy-key management; the default GITHUB_TOKEN can never work.

Scaling characteristics. Three cost axes: (1) Forge servers — one per open PR, so cost scales with PR concurrency, and label-gating or a draft-PR filter may be warranted; (2) Git API rate limits — one key registration per provision and one comment per PR, negligible at normal volume but visible during bulk backfills; (3) key sprawl — every teardown must delete its key, so teardown reliability is a security-hygiene concern, not just a cost one. A weekly audit of Forge sites and repository deploy keys against open PRs is a cheap control.

Failure modes.

The two soft-degrade modes are the ones that will bite in practice: pipelines stay green while previews lack keys or authors lack feedback, and nobody notices until someone asks why their PR has no environment URL.

Ramp-up. An experienced Laravel/CI engineer can complete the upgrade and concurrency fix in well under a day for a single repository. The long pole is organizational, not technical: obtaining a GitHub App permission upgrade (which requires an installation owner to accept new permissions) or provisioning a suitably scoped PAT. Budget a security review alongside the engineering work, and treat the credential model decision as the actual adoption gate.

Verdict. Adopt v2.1.0. It fixes a hard blocker, adds self-hosted GitLab support at no configuration cost to existing users, and its failure messages are better than most tools in this category. The residual risks — elevated token scope, private-key custody, and soft-degrade silence — are manageable with a runbook and a dedicated credential, but they should be accepted deliberately rather than inherited by default.