Super-charging Laravel Forge Deployments with Environment Variables

Jun, 24 2022#forge

Aside from provisioning servers and creating sites, Laravel Forge can do so much more, including deploying code to your sites.

When you install a repository for your site, Forge automatically creates a deployment script that is executed every time you deploy your site. A deployment script is Bash code that tells Forge how to deploy your site, install Composer dependencies, build frontend assets, and reload the PHP-FPM process.

One of the biggest benefits of using environment variables is that you can easily change the site's version of PHP at any time, without needing to change your deployment script too. For example, by using the $FORGE_PHP environment variable instead of invoking the php binary directly, Forge will automatically utilize the correct version of PHP for you.

A default deployment script for a Laravel site looks something like this:


git pull origin $FORGE_SITE_BRANCH
$FORGE_COMPOSER install --no-interaction --prefer-dist --optimize-autoloader

( flock -w 10 9 || exit 1
    echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock

if [ -f artisan ]; then
    $FORGE_PHP artisan migrate --force

As you can see, the default deployment script already makes use of some of the environment variables that are injected into the process at the time of deployment.

Forge's built-in environment variables can be quickly identified since they are all prefixed with $FORGE_.

Forge doesn't stop there. You may also inject your own environment variables when deploying via the deployment trigger URL. If we take our deployment trigger URL:

We can append additional query parameters to the URL and they will automatically be converted into environment variables. For example, if we append &env=staging, Forge will inject a $FORGE_VAR_ENV variable that evaluates to "staging". Armed with additional environment variables, we can fine-tune what our deployment script does depending on how the deployment is started.

So, what are some of the cool things that we can do with environment variables?

Prevent Deployments With "wip" Commits

if [ $FORGE_DEPLOY_MESSAGE =~ "wip" ]; then
    echo "The current code is a work in progress. Exiting..."
    exit 1

Prevent Deployments Triggered Through the Forge Dashboard

if [ $FORGE_MANUAL_DEPLOY -eq 1 ]; then
    echo "Manual deployments are not allowed. Exiting..."
    exit 1

Notify Bugsnag of Releases

This example requires you to be using the Laravel Bugsnag package.

$FORGE_PHP artisan bugsnag:release \
  --repository "" \
  --revision "${FORGE_DEPLOY_COMMIT}" \
  --builder "${FORGE_DEPLOY_AUTHOR}"

If you don’t have a Forge account, now is a great time to sign up! Forge allows you to painlessly create and manage PHP servers which include MySQL, Redis, Memcached, database backups, and everything else you need to run robust, modern Laravel applications.

By James Brooks

Engineering Team Lead at Laravel, building Forge, Vapor & Envoyer.

Find me on Twitter, GitHub or my blog.

Follow the RSS Feed.