Forge: Deployment Webhook Improvements

Laravel Forge's "quick deploy" feature gives your team a seamless push-to-deploy experience. Whenever new code is pushed to your deployed branch, Forge will kick off a new deployment. This ensures that your site is always running your project's latest code. Forge will also display the commit information in the "Deployments" table, so you can keep track of what was deployed, and when.

Unfortunately, projects triggering deployments via the "Deployment Trigger" URL or using a custom source control provider could not take full advantage of this feature - until now.

Improved Quick Deploy For Custom Providers

Many sites on Forge using a custom source control provider are actually using a first party supported git provider, i.e., GitHub, GitLab, or Bitbucket, as their source control host, because doing so enables a team with complex project access requirements to deploy repositories that are not contained in their Forge linked source control account.

For these sites Forge will now detect the first party supported git provider and recommend setting up webhooks via the provider's native webhook functionality.

Quick Deploy Instructions

Once set up, when Forge receives a "push" webhook from GitHub, GitLab, or Bitbucket, the commit information will now be detected and populated in the deployments table. The FORGE_DEPLOY_COMMIT, FORGE_DEPLOY_AUTHOR, and FORGE_DEPLOY_MESSAGE environment variables will also be populated for use in the site's deploy script.

Manually Providing Commit Details

For sites using a different source control provider altogether or triggering deploys from CI, Forge has no way of knowing the commit hash, author, branch, or message. That is why we have rolled out the ability to pass this information through to Forge via query parameters in the Deployment Trigger URL.

Forge has introduced 4 reserved query parameters you may use to pass this information through:

forge_deploy_branch: The branch that contains the commit. Forge will only trigger a deployment if the branch matches the site's currently deployed branch.
forge_deploy_commit: The hash of the commit. This will be visible in the "Deployments" table and be available as the FORGE_DEPLOY_COMMIT environment variable in your deploy script.
forge_deploy_author: The author of the commit. This will be visible in the "Deployments" table and be available as the FORGE_DEPLOY_AUTHOR environment variable in your deploy script.
forge_deploy_message: The commit message. This will be available as the FORGE_DEPLOY_MESSAGE environment variable in your deploy script.

For example, in your CI script you could pass commit message "WIP" through to Forge when calling the deployment trigger URL:

COMMIT_MESSAGE="WIP"

curl "https://forge.laravel.com/servers/676709/sites/1968614/deploy/http?token=xxxx&forge_deploy_message=$COMMIT_MESSAGE"

We hope these improvements will make working with custom source control providers and deploying via CI a nicer experience. If you have any further suggestions on ways we can improve custom integrations with Forge, we'd love to hear them.