Veyoze Laravel Package

Getting Started

Harbor is a CI-side tool, not a runtime dependency — you won't be calling it from controllers or models. It boots inside a GitHub Actions (or similar) runner, talks to the Forge API, and provisions a temporary preview site for each pull request.

Install the package in the Laravel app you want previews for:
```
composer require mehrancodes/laravel-harbor --dev
```
Harbor v2 requires PHP 8.2+. If you use the kirschbaumdevelopment/laravel-test-runner container, switch to :8.3 — the older docs examples pinned :8.1 and will break.
Publish the config and skim config/harbor.php before touching env vars. Most of what the release notes describe (git_api_provider, deploy_key, git_api_url) maps to keys here.
Copy a workflow from the docs into .github/workflows/. Two jobs are the minimum: harbor-provision on pull_request: [opened, synchronize, reopened] and harbor-teardown on pull_request: [closed]. Both need concurrency groups (see below).
First use case: open a PR, watch the Actions log for INFO ---> Creating a new site., then visit the preview URL Harbor prints. If you only want the site provisioning without PR comments or deploy keys, you can start with just FORGE_API_TOKEN, FORGE_SERVER_ID, and FORGE_GIT_REPOSITORY_URL/BRANCH.

The docs pages worth bookmarking first: Git Providers and Announcement Comments.

Implementation Patterns

Split clone-provider from API-provider. This is the structural change in v2.1. FORGE_GIT_PROVIDER tells Forge how to clone the repo at runtime; FORGE_GIT_API_PROVIDER tells Harbor which REST API to call for deploy keys and PR/MR comments. They default to the same value but diverge as soon as you're on self-hosted Git:

env:
  FORGE_GIT_PROVIDER: custom           # Forge clones from a custom URL
  FORGE_GIT_REPOSITORY_URL: https://gitlab.example.com/team/app.git
  FORGE_GIT_API_PROVIDER: gitlab-custom
  GIT_API_URL: https://gitlab.example.com/api/v4
  GIT_TOKEN: ${{ secrets.GITLAB_TOKEN }}
  FORGE_DEPLOY_KEY: true

Provider inference. If FORGE_GIT_PROVIDER=custom, Harbor sniffs the API provider from a github.com or gitlab.com FORGE_GIT_REPOSITORY_URL. Only set FORGE_GIT_API_PROVIDER explicitly for self-hosted hosts — otherwise you're just duplicating what Harbor already figured out.

Deploy keys per preview. With FORGE_DEPLOY_KEY=true, Harbor generates a keypair, registers the public half on GitHub/GitLab, passes both halves to Forge, and removes the key on teardown. This is the pattern for private repos where the preview site needs read access but you don't want a shared org-wide key.

Bring-your-own keypair when Harbor can't reach the Git API (air-gapped runners, restricted tokens, on-prem Git it can't authenticate against):

FORGE_DEPLOY_KEY_PUBLIC: ${{ secrets.DEPLOY_KEY_PUBLIC }}
FORGE_DEPLOY_KEY_PRIVATE: ${{ secrets.DEPLOY_KEY_PRIVATE }}

Harbor still hands both halves to Forge; you just skip the registration step.

Announcement comments on GitLab. PR/MR commenting now works on GitLab merge requests. Set GIT_COMMENT_ENABLED=true and GIT_ISSUE_NUMBER to the MR iid (that's the per-project number shown in the UI, not the global id from the API).

Concurrency groups — add these even if you skip everything else:

jobs:
  harbor-provision:
    concurrency:
      group: harbor-${{ github.event.pull_request.number }}
      cancel-in-progress: false

Without it, two rapid pushes to the same PR (or reopen-after-push) race to create the same site and one job dies with site: The site must be installed before it can be deployed. The same group should be applied to teardown so it can't run mid-provision.

Gotchas and Tips

The default GITHUB_TOKEN cannot manage deploy keys. This is the most common v2.1 failure mode. You'll see Forbidden. GIT_TOKEN cannot manage deploy keys on this repository. Fix it one of two ways:

GitHub App token (via actions/create-github-app-token): grant Repository permissions → Administration: Read and write, then accept the updated permissions on the installation. Changing the app's permissions without re-accepting on the installation is a silent no-op.
Personal access token: needs the repo scope.

Deprecation: FORGE_GITHUB_DEPLOY_KEY is now FORGE_DEPLOY_KEY. The old name still works but emits WARNING ---> FORGE_GITHUB_DEPLOY_KEY is deprecated. Provisioning continues, so this won't fail CI on its own. Rename it now to avoid breakage in a future major.

- FORGE_GITHUB_DEPLOY_KEY: true
+ FORGE_DEPLOY_KEY: true

Warnings are not failures — but they mean something didn't happen. Harbor deliberately continues when it can't reach your Git API. Two messages to recognize:

Harbor has no Git API configured, so the deploy key was not registered automatically. — Harbor printed the public key to the log; you can add it manually, or set FORGE_GIT_API_PROVIDER + GIT_TOKEN.
Harbor has no Git API configured, so no comment was posted. — same cause. Also double-check GIT_COMMENT_ENABLED=true and GIT_ISSUE_NUMBER; missing either will suppress comments with no warning about those.

Neither warning will fail the build, so if provisioning suddenly stops posting PR comments after a runner change, grep the log for WARNING before assuming Harbor is broken.

FORGE_GIT_PROVIDER is now validated up front against github, gitlab, gitlab-custom, bitbucket, custom. A typo fails before Harbor ever calls Forge — good, but if you had a junk value sitting in a repo secret, it surfaces now. custom additionally requires FORGE_GIT_REPOSITORY_URL.

Debugging CI failures. Harbor's log lines follow INFO --->, WARNING --->, FAIL ---> prefixes. Read them top-down; the FAIL is usually the consequence of a WARNING two lines above. ForgeValidationException and ValidationException mean Forge (or Harbor's own config validator) rejected the payload before any site was created — the error text names the exact field.

Teardown cleans up deploy keys it registered. If you brought your own keypair via FORGE_DEPLOY_KEY_PUBLIC/PRIVATE, Harbor still passes it to Forge but won't have removed anything from your Git provider — that's yours to rotate.

Extension points. The custom provider plus GIT_API_URL is the intended hook for self-hosted Git; there's no plugin API for arbitrary providers. For anything beyond GitHub/GitLab, you're on custom for cloning and manual key management, with comments disabled.

PHP version drift. v2 needs 8.2+, and pinning a runner container one minor behind the app is an easy way to spend an afternoon on a stack trace that only exists in CI. Align the runner image with whatever the app itself targets.