Veyoze Laravel Package

Technical Evaluation

Harbor is a Laravel/PHP CI orchestration package that provisions and tears down per-pull-request preview environments on Laravel Forge, using Git provider APIs for deploy keys and PR/MR comments. v2.1.0 is a meaningful capability release rather than a maintenance drop: it adds GitHub/GitLab provider support, restores deploy-key creation on Forge’s current API, separates the Git provider used by Forge for cloning from the Git API provider Harbor uses for automation, and introduces GitLab MR comment support.

Architecture fit: Harbor sits outside the application runtime. It is a workflow/CI dependency, not a Composer library consumed by production Laravel code. That makes it a low-blast-radius adoption for the product runtime but a high-importance dependency for preview-environment automation. The new split between FORGE_GIT_PROVIDER and FORGE_GIT_API_PROVIDER is architecturally sound: Forge needs to know how a site clones a repository, while Harbor needs API credentials and API base URLs to manage deploy keys and comments. Conflating those concerns was a limitation; v2.1.0 corrects it.

Integration feasibility: Good for teams already using Laravel Forge and GitHub Actions or GitLab CI. The package is installable via Composer, configured through environment variables, and invoked from CI jobs. The release preserves default GitHub setups and pre-v2 “GitHub custom” setups without workflow changes. The main integration friction is credential scope, not code: GitHub App tokens need Repository permissions → Administration: Read & write, personal access tokens need the repo scope, and the default GITHUB_TOKEN in Actions cannot manage deploy keys. Self-hosted GitLab requires GIT_API_URL; otherwise Harbor falls back to printing the public key for manual registration.

Technical risk: Moderate, concentrated in credentials and lifecycle edge cases rather than application correctness.

• Deploy-key permission failures: A 403 Forbidden stops provisioning if the token cannot manage deploy keys. The error message is explicit, which reduces diagnosis time, but the failure occurs during site creation.
• Manual key fallback: If Harbor cannot reach the Git API, provisioning continues but the deploy key is not registered automatically. This is a recoverable degradation, but it breaks the “hands-off preview environment” promise and requires a manual step or a follow-up workflow fix.
• Concurrency races: The release explicitly calls out a race where two runs for the same PR attempt to create the same site and one fails with site: The site must be installed before it can be deployed. This is an operational defect unless per-PR concurrency groups are added to both provision and teardown jobs.
• Deprecation debt: FORGE_GITHUB_DEPLOY_KEY still works as an alias but will be removed in a future major release. Teams should rename it now to avoid a future breaking change.
• Stricter validation: FORGE_GIT_PROVIDER is now validated against github, gitlab, gitlab-custom, bitbucket, and custom. Typos fail early, which is good, but existing workflows with non-standard values may fail before Forge is called. custom also requires FORGE_GIT_REPOSITORY_URL.
• PHP runtime floor: Harbor v2 requires PHP 8.2+. Workflows still using kirschbaumdevelopment/laravel-test-runner:8.1 must move to :8.3 or another 8.2+ image.

Key questions:

• Which Git provider and hosting model will the team use: GitHub.com, GitLab.com, self-hosted GitLab, or custom Git URLs?
• Will deploy-key automation use a GitHub App or a personal access token? Who owns the app installation and permission review?
• Are preview environments required for fork-based or external-contributor PRs, where secrets and deploy-key permissions may not be available?
• What is the expected PR concurrency per repository, and will per-PR concurrency groups be added to both provision and teardown jobs?
• Is the team prepared to rotate deploy keys and Git API tokens, and does the teardown path reliably remove registered keys?
• Does the team need PR/MR comments as part of the developer experience, or is comment automation optional?

Integration Approach

Stack fit: Strong fit for Laravel teams already standardized on Forge for infrastructure and GitHub Actions or GitLab CI for delivery. Harbor does not replace Forge, Terraform, or existing deployment pipelines; it automates the per-PR preview-environment lifecycle around them. Teams not using Forge should treat this package as out of scope. Teams using GitHub.com with default settings have the simplest path; self-hosted GitLab and custom Git URLs are supported but require explicit API configuration.

Migration path: For existing Harbor v2.0.x users, v2.1.0 is an upgrade-and-rename release, not a re-architecture.

1. Upgrade the package to v2.1.0.
2. Confirm the CI runner uses PHP 8.2+; update kirschbaumdevelopment/laravel-test-runner from :8.1 to :8.3 if applicable.
3. Rename FORGE_GITHUB_DEPLOY_KEY to FORGE_DEPLOY_KEY. The old variable remains a working alias with a warning, but should not be left in place.
4. If using GitHub.com defaults, no further provider changes are required.
5. If using GitLab.com or self-hosted GitLab, set FORGE_GIT_API_PROVIDER and, for self-hosted instances, GIT_API_URL.
6. Add per-PR concurrency groups to provision and teardown jobs before enabling the workflow broadly.
7. Verify token scopes: GitHub App needs Administration read/write; PAT needs repo; default GITHUB_TOKEN is insufficient for deploy-key management.

For teams adopting Harbor for the first time, start with a single non-critical repository and the default GitHub path. Validate site creation, deploy-key registration, teardown, and comment behavior before rolling out to multiple repositories.

Compatibility: The release is backward-compatible for default GitHub setups and pre-v2 “GitHub custom” setups. The FORGE_GITHUB_DEPLOY_KEY alias preserves existing workflows until the next major release. The stricter FORGE_GIT_PROVIDER validation is the main compatibility sharp edge: values outside the allowed set now fail early. Self-hosted GitLab users need GIT_API_URL; without it, deploy keys are generated but not registered automatically, and comments are skipped. FORGE_DEPLOY_KEY_PUBLIC and FORGE_DEPLOY_KEY_PRIVATE provide an escape hatch for bring-your-own-keypair scenarios where Harbor cannot reach the Git API.

Sequencing:

1. Baseline audit: Inventory repositories, CI providers, Forge sites, current Harbor versions, PHP versions, and existing environment-variable names.
2. Credential readiness: Decide GitHub App vs PAT, confirm permission scopes, and identify who can approve installation permission updates. Confirm GIT_TOKEN availability for comment automation.
3. Pilot upgrade: Upgrade one repository, rename the deploy-key variable, and run a full PR provision/teardown cycle.
4. Concurrency hardening: Add per-PR concurrency groups to both provision and teardown jobs before increasing PR volume.
5. Provider expansion: Enable GitLab or self-hosted GitLab only after confirming FORGE_GIT_API_PROVIDER, GIT_API_URL, and token scopes in a non-production repository.
6. Rollout: Apply the validated workflow template across repositories and remove deprecated variables.

Operational Impact

Maintenance: Low-to-moderate ongoing maintenance. The package is a CI dependency, so upgrades are periodic and should be coordinated with workflow changes. The main maintenance item is deprecation cleanup: rename FORGE_GITHUB_DEPLOY_KEY to FORGE_DEPLOY_KEY now, before the alias is removed in a future major release. Teams using multiple Git providers should maintain a small provider matrix documenting which env vars and token scopes apply to GitHub.com, GitLab.com, self-hosted GitLab, and custom Git URLs. Deploy keys and Git API tokens need an ownership model and rotation policy; teardown removes keys, but token lifecycle is still the team’s responsibility.

Support: The release improves supportability. Failure messages are specific: the 403 Forbidden message states exactly which GitHub App permission or PAT scope is missing; the unregistered-key warning prints the public key and explains the missing Git API configuration; the comment-skipped warning identifies the missing provider and token. That reduces escalation time. However, support still needs runbooks for four scenarios: deploy-key permission denial, unregistered deploy key fallback, skipped PR/MR comments, and git_provider validation failure. The concurrency race also needs a runbook entry because it presents as a confusing Forge deployment error, not as a Harbor configuration error.

Scaling: Harbor scales with the number of open PRs and the rate limits of Forge and the Git provider APIs. Two scaling constraints stand out. First, per-PR concurrency is mandatory for reliable operation: without it, rapid pushes or PR reopen events can race to create the same site. Second, deploy-key registration and comment posting consume Git provider API quota; high-volume repositories should monitor rate limits and avoid unnecessary comment automation. Forge site limits and plan capacity are the practical ceiling for parallel preview environments. Teams should define a maximum concurrent preview count and a teardown SLA so stale sites do not accumulate.

Failure modes:

• Provisioning stops on deploy-key registration: 403 Forbidden from GitHub/GitLab. Cause: insufficient token scope. Fix: grant GitHub App Administration read/write or PAT repo scope; do not use default GITHUB_TOKEN.
• Provisioning continues with manual key registration: Harbor cannot reach the Git API. Cause: missing GIT_TOKEN, missing FORGE_GIT_API_PROVIDER, or custom/self-hosted host without GIT_API_URL. Fix: configure the API provider and token, or add the printed public key manually.
• PR/MR comment skipped: Same root cause as above, plus GIT_COMMENT_ENABLED and GIT_ISSUE_NUMBER must be set. Provisioning continues.
• Validation error before Forge call: FORGE_GIT_PROVIDER is not one of the allowed values, or custom is used without FORGE_GIT_REPOSITORY_URL. Fix: correct the env var.
• Site creation race: Two workflow runs for the same PR create the same site; one fails with site: The site must be installed before it can be deployed. Fix: add per-PR concurrency groups with cancel-in-progress: false to provision and teardown jobs.
• PHP version mismatch: CI runner uses PHP 8.1 or lower. Fix: move to PHP 8.2+; for the Laravel test runner container, use :8.3.
• Stale preview environments: Teardown not triggered or failing. Operational risk: orphaned Forge sites and deploy keys. Mitigate with scheduled cleanup and teardown monitoring.

Ramp-up: Moderate. A developer familiar with Laravel, Forge, and GitHub Actions can complete a pilot in under a day if token permissions are already correct. The learning curve is mostly credential and provider configuration, not package internals. Allocate time for: understanding the FORGE_GIT_PROVIDER vs FORGE_GIT_API_PROVIDER distinction, setting up GitHub App permissions or PAT scopes, adding concurrency groups, and documenting the manual deploy-key fallback. Teams using self-hosted GitLab should budget additional time for GIT_API_URL and token validation. Overall, v2.1.0 is a worthwhile upgrade for teams standardizing preview environments across GitHub and GitLab, provided they treat credential scopes and per-PR concurrency as release blockers rather than follow-up cleanup.