- How do I install and run Veyoze for Laravel Forge preview environments?
- Install the package with Composer, typically as a dev or CI dependency, then call the Veyoze CLI from your CI workflow such as GitHub Actions or GitLab CI. It is a workflow dependency rather than runtime application code, so it does not need to be loaded by your production Laravel app. Configure Forge and Git credentials as environment variables before invoking it.
- Which Git providers does Veyoze support for deploy keys and pull request comments?
- Veyoze v2.1.0 supports GitHub and GitLab automation, including deploy-key creation and GitLab merge request comments. Forge's clone provider is configured separately from the Git API provider Veyoze uses for automation, so you can use a different automation API where needed. The validated provider list also includes bitbucket, gitlab-custom, and custom.
- What PHP version do I need to run Veyoze?
- Veyoze v2 requires PHP 8.2 or newer. If your CI still uses an older runner image such as laravel-test-runner:8.1, move it to an 8.2 or 8.3 image before upgrading. The PHP floor applies to the CLI workflow environment, not just your Laravel app's deployment target.
- What is the difference between FORGE_GIT_PROVIDER and FORGE_GIT_API_PROVIDER?
- FORGE_GIT_PROVIDER tells Forge how a site clones the repository, while FORGE_GIT_API_PROVIDER tells Veyoze which Git API to use for deploy keys and comments. Splitting them is useful when Forge clones through one mechanism but automation needs different API credentials or a custom base URL. FORGE_GIT_PROVIDER is validated against github, gitlab, gitlab-custom, bitbucket, and custom, and custom also requires FORGE_GIT_REPOSITORY_URL.
- Why does Veyoze return 403 Forbidden when creating a Forge deploy key?
- A 403 usually means the Git token cannot manage deploy keys for the repository. GitHub App tokens need Repository permissions with Administration read and write, and personal access tokens need the repo scope. The default GITHUB_TOKEN in GitHub Actions cannot manage deploy keys, so use a dedicated App or PAT with the right scope.
- Should I use a GitHub App or a personal access token with Veyoze?
- Both approaches are supported as long as the credential can manage repository deploy keys. A GitHub App is usually better for organization-owned repos because permissions and installation ownership are centralized and easier to audit. A personal access token is quicker to set up but ties automation to a user and needs the repo scope.
- How do I avoid the race where two Veyoze runs create the same Forge site?
- Add a per-pull-request concurrency group to both the provision and teardown CI jobs. Without that, two runs for the same PR can attempt to create the same site, and one can fail with the message that the site must be installed before it can be deployed. The concurrency group should key on the repository and PR number so provisioning and cleanup cannot overlap for the same preview.
- Does Veyoze work with self-hosted GitLab?
- Yes, but self-hosted GitLab requires GIT_API_URL so Veyoze knows the API base URL for deploy-key and comment operations. If that URL is missing or unreachable, Veyoze falls back to printing the public key so you can register it manually. For custom Git hosting, use the custom provider and set FORGE_GIT_REPOSITORY_URL.
- What happens if Veyoze cannot reach the Git API during provisioning?
- Provisioning can continue, but the deploy key is not registered automatically and the preview environment may not be fully hands-off. Veyoze prints the public key so you can add it manually, which is a recoverable degradation rather than a hard failure. To keep full automation, fix API connectivity or credentials and let Veyoze manage the key.
- Is FORGE_GITHUB_DEPLOY_KEY deprecated in Veyoze v2?
- Yes, FORGE_GITHUB_DEPLOY_KEY still works as an alias in v2 but is slated for removal in a future major release. Rename it to the new provider-aware configuration now so your workflows do not break on the next major upgrade. While upgrading, also check that FORGE_GIT_PROVIDER uses one of the validated values because typos now fail before Forge is called.