Features

This page explains how the deployment scripts works and which features it has. All the information on this page applies to both the GitHub, GitLab and Bitbucket deployment scripts.

TLDR: this deployment script works the same as Laravel Envoyer (maybe even better). It can deploy all your Laravel applications for years to come. You'll love it if you give it a try.

An overview of a typical deployment:

1. You push a commit to a specific branch
2. GitHub, GitLab or Bitbucket starts running the workflow
3. The workflow builds your application
   • composer install --no-dev
   • npm ci
   • npm run production
4. The workflow uploads the application to your server
5. The workflow runs the deployment script on your server

The deployment script then:

• Runs all of Laravel's optimization commands
• Sets correct file permissions (if necessary)
• Runs your custom "before-activation" hook
• Enables the new release
• Runs your custom "after-activation" hook
• Flushes OPCache
• Cleans up old releases

Configuring the workflow

The GitHub, GitLab or Bitbucket workflow only runs when you commit to a specific branch. You can configure this branch in the workflow file. You can also configure it to run for multiple branches, develop and main for example.

The workflow has two steps: a build step and a deployment step. The deployment step is where you configure your server details. You can also configure which PHP executable should be used on your server.

You can copy and paste the deployment step to configure multiple servers. For example, you can easily configure the script to deploy the main branch to your production server, and the develop branch to your staging server.

The workflow doesn't run tests or static analysis by default, but you can add this yourself in the build step. The deployment will be cancelled if any test fails, ensuring you can't deploy a broken release.

Benefits of the workflow build step

The GitHub, GitLab or Bitbucket runner will build your application, this has some benefits:

First of all, you don't need npm, composer or git installed on your server. These programs are only necessary while building your application, which all happens on the runner.

Second, the node_modules directory doesn't end up on your server, this saves a lot of disk space. The node_modules directory is only necessary while building your production javascript bundle. When the deployment script uploads your application to your server, the node_modules aren't included.

Third, you don't put load on your server during deployments with slow build steps. Again, these steps happen on a runner, not on your server.

Lastly, if any part of the build fails, the deployment will be cancelled. This way you can never break your production environment because of build problems.

The bash deployment script

The bash deployment script never has to be modified (but you could if you wanted to). Any customizations that your application might need can be put in hooks.

The deployment script prepares the new release, runs the hooks, enables the new release, and then cleans up after itself. It is also full of safety-checks that stop the deployment if anything is out of order.

Flushing OPCache

The deployment script flushes OPCache after each deployment. It does this by calling PHP's opcache_reset() function via a web request. This is the proper way of flushing OPCache, and it does not require sudo or restarting your PHP-FPM.

Setting correct file permissions

The deployment script detects if file permissions have to be changed, and if necessary configures them correctly. To read more exactly how this works, check out the correct file permissions blog post.

Before and after activation hooks

Any customization your application might need can be put in the before and after activation hooks.

The before activation hook runs after your application is fully built, but before the new deployment has been activated. By default, this hook run database migrations and all of Laravel's optimization commands.

The after activation hook runs after the new deployment has been activated. By default, this hook restarts your queue workers. This hook is the perfect place to fire off a webhook to notify your team of the new deployment, or to run a job that generates a new sitemap.