Skip to main content

​
Introduction

Laravel Forge now offers zero-downtime deployments for all new sites.
While Laravel Forge now offers zero-downtime deployments, you may choose to use the first-party integration with Envoyer to simultaneously deploy projects across multiple servers. Zero-downtime deployments ensure you avoid those brief milliseconds of downtime while the server updates your code.

​
Creating an Envoyer API token

To kick things off, you’ll need active subscriptions for both Laravel Forge and Envoyer. Once you’re set up, navigate to your Envoyer dashboard and create a new API token. At a minimum, Laravel Forge requires the following scopes: 
deployments:create
projects:create
servers:create
To future-proof the integration, consider providing Laravel Forge with additional access permissions. You can update your Envoyer’s API token in Forge at any point.

​
Linking your Envoyer account to Laravel Forge

To link Laravel Forge with your Envoyer API token, navigate to your organization’s settings and toggle on the “Envoyer” option. You’ll be prompted to enter your Envoyer API token. After submitting the token, Forge will first verify it and then enable the integration.

​
Envoyer sites in Laravel Forge

It is no longer possible to link newly created Laravel Forge sites to Envoyer projects. Instead, you should create a new Envoyer project and then import your Laravel Forge server and site into that project. For more information, see the “Migrating an existing site to Envoyer” section below.
To deploy your Envoyer project within Laravel Forge, click the “Deploy” button, just as you would with any other site in Forge. The “Deployment Trigger URL” is also available for use in a CI environment. Additionally, Laravel Forge has been updated to align perfectly with Envoyer projects:
  • Commands are executed from the /current directory.
  • The site’s “Environment” panel will display a read-only version of the .env file. Continue to use Envoyer to manage your environment file, especially since it may need to be synchronized across multiple servers.
  • The site’s “Packages” panel is disabled to ensure the auth.json file remains intact through future deployments.

​
Migrating existing sites to Envoyer

Sites previously connected to Envoyer can be migrated to Laravel Forge’s native zero-downtime deployment system. To do so, navigate to the site’s “Overview” panel and click “Migrate to Forge”. The Envoyer project will first be checked for compatibility. If compatible, the migration can be completed. To complete the migration, you will need to provide your environment key for the Envoyer project. This allows Laravel Forge to access the .env file for the project. If the Envoyer project is configured to use Heartbeats, Laravel Forge will also provide you with a list of new heartbeat URLs. You will need to update your application to use these new URLs.

​
Requirements

There are a few requirements that must be met before migrating an existing Envoyer site to Laravel Forge:
  1. Your Envoyer project must be connected to a single server.
  2. Must not be using GitLab Self-Hosted as the Git repository.
  3. Your organization must be connected to the Envoyer integration.
⌘I