- How do I install mehrancodes/laravel-harbor in a Laravel project?
- Install it as a Composer dev dependency with composer require mehrancodes/laravel-harbor --dev, then publish the laravel-harbor configuration. Harbor is CLI tooling for CI, not a runtime dependency of the deployed application. You invoke its Artisan commands from your pipeline rather than from application code.
- Does Laravel Harbor support self-hosted GitLab and deploy keys?
- Yes. Version 2.1.0 adds FORGE_GIT_API_PROVIDER with support for github, gitlab, gitlab-custom, bitbucket, and custom. Deploy keys work again on Harbor v2: Harbor generates a keypair before site creation, registers the public key with the Git host, passes both halves to Forge, and deletes the key on teardown. Self-hosted GitLab is the main capability unlock, and custom providers require FORGE_GIT_REPOSITORY_URL.
- What Laravel versions does laravel-harbor support?
- Harbor is developer tooling invoked from CI, so its Laravel constraint mainly affects the Artisan command surface rather than your app's runtime. Check the current illuminate/support and PHP requirements in the package's composer.json before upgrading. Test the Harbor commands against the same Laravel version your CI job uses.
- How do I migrate from FORGE_GITHUB_DEPLOY_KEY to FORGE_DEPLOY_KEY?
- FORGE_DEPLOY_KEY is the new name in v2.1.0, while FORGE_GITHUB_DEPLOY_KEY still works as an alias and emits a CI log warning. Migrate now because the alias is scheduled for removal in the next major release. If Harbor cannot reach your Git host, use FORGE_DEPLOY_KEY_PUBLIC and FORGE_DEPLOY_KEY_PRIVATE as escape hatches.
- What credentials does Laravel Harbor need, and is it safe for production CI?
- Harbor holds Forge and Git API credentials in CI, and v2.1.0 deploy-key registration requires a GitHub App with Administration read/write or a PAT with repo scope. The default GITHUB_TOKEN in GitHub Actions cannot register deploy keys. Treat this as a security review item: use a dedicated app or token per repository and define rotation and offboarding ownership.
- How do I prevent duplicate Forge sites and race conditions with Laravel Harbor?
- Use per-pull-request concurrency groups in CI so only one Harbor run per PR executes at a time. Without that, rapid pushes or PR reopen can cause a hard failure because a site must be installed before it can be deployed, and they can leave orphaned or duplicate Forge sites. Harbor does not manage concurrency for you; it remains a user-side responsibility.
- What happens if no Git API provider is configured in Laravel Harbor?
- Harbor warns and continues: the Forge site is created, but the deploy key is not registered and the PR comment is skipped. That availability-first default means a green pipeline is not proof that preview-environment automation fully worked. Watch CI logs for Harbor warnings and configure FORGE_GIT_API_PROVIDER explicitly if you need deploy keys or comments.
- Does Laravel Harbor support Bitbucket?
- Validation accepts bitbucket, but there is no Bitbucket API provider. In practice that means the configuration validates while deploy-key registration and PR comments silently degrade. If Bitbucket is in scope, confirm the behavior in your own pipeline before relying on full preview automation.
- How should I test Laravel Harbor in CI without breaking real infrastructure?
- Harbor drives real Forge and Git APIs, so there is no true dry-run mode described in the release. Test first against a throwaway Forge server and repository with dedicated credentials, and assert on Harbor's warning-level output for degraded paths. Clean up preview sites on teardown and keep credentials separate from production.
- What are alternatives to Laravel Harbor, and how is it maintained?
- Alternatives include manual Forge site provisioning per PR, Forge's own preview deployment features where available, or CI scripts that call the Forge API directly. Harbor's differentiator is its packaged Artisan command workflow plus deploy-key registration and PR comments. Version 2.1.0 is a capability release that fixes deploy keys and adds provider abstraction, but review release notes for scheduled breaking changes and pin the version in CI.