> ## Documentation Index
> Fetch the complete documentation index at: https://cloud.laravel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployments

> Learn how deployments work in Laravel Cloud, including builds, push to deploy, deploy hooks, and zero-downtime releases.

## Introduction

Deployments in Laravel Cloud happen whenever you have new code to release, new resources to attach, or environment settings that you want to update.

When a new deployment is triggered, Laravel Cloud will take your code and environment settings, build a Docker image configured for your chosen PHP version, and then run your build and deploy commands.

Once your build completes successfully, the existing deployment will be gracefully terminated (allowing any running processes to complete) and the new deployment will be brought online with zero downtime.

<Frame>
  <img src="https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/deployments.png?fit=max&auto=format&n=MkfTsQSKGENWqY-2&q=85&s=5df0c34d2d657e2bb54ea8158edb0609" width="1171" height="483" data-path="images/deployments.png" />
</Frame>

## Deploy options

### Push to deploy

Every time you push new code to your remote Git branch, a new deploy is automatically triggered. <b>Push to deploy is enabled by default</b> on all environments. To change this setting, go to Settings > Deployments.

### Deploy hooks

If you prefer to trigger a deployment via an HTTP endpoint, you can enable the "Deploy hook" option in Settings > Deployments. When enabled, you will be provided a URL that you can make a POST request to as part of your CI/CD flow. You can refresh your URL anytime from the Deployments settings.

You can also deploy a specific commit by passing a `commit_hash` query parameter to the deploy hook URL. The commit hash should belong to the branch configured for the environment.

```shell theme={null}
curl -X POST "https://your-deploy-hook-url?commit_hash=abc123def456"
```

If no commit hash is provided, the latest commit from the environment's branch will be deployed.

#### Example using GitHub Actions

Deploy hooks are perfect for integrating Laravel Cloud with your CI / CD pipeline. Here's a complete example using GitHub Actions:

1. First, add your deploy hook URL as a secret in your GitHub repository:
   * Go to your GitHub repository settings
   * Navigate to Secrets and variables → Actions
   * Add a new secret named `LARAVEL_CLOUD_DEPLOY_HOOK` with your deploy hook URL

2. Create a `.github/workflows/deploy.yml` file in your repository:

```yaml theme={null}
name: Deploy to Laravel Cloud

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Laravel Cloud
        run: |
          curl -X POST "${{ secrets.LARAVEL_CLOUD_DEPLOY_HOOK }}?commit_hash=${{ github.sha }}"
```

3. Commit and push the workflow file to trigger your first deployment.

Unlike traditional deployment processes that require installing dependencies and running build commands in CI, Laravel Cloud handles all of this for you. The deploy hook simply triggers Laravel Cloud to:

* Pull your code from the specified commit
* Run your configured build commands
* Run your configured deploy commands
* Deploy your application with zero downtime

### Manual

You can trigger a deployment from the Laravel Cloud dashboard anytime by clicking the "Deploy" button from the Environment overview page or Deployments page. After updating environment settings, your changes are staged until you deploy them. Review everything that is pending and deploy the batch from the staged changes banner, or use the "Deploy" button at any time.

## Troubleshooting

### Framework or runtime version not supported

<Tabs>
  <Tab title="Laravel">
    Laravel Cloud requires Laravel 9 or greater. In addition, you should be using the latest minor version of the `laravel/framework` Composer package. The minimum minor versions required are:

    * Laravel 11: `v11.41.3`
    * Laravel 10: `v10.48.28`
    * Laravel 9: `v9.52.20`

    <Tip>
      Watch [this video](https://youtu.be/95iC9L-3CxY) to learn more about fixing this framework error.
    </Tip>

    If you receive an error during a deployment that *"The \[laravel/framework] package was found in the \[composer.lock] file, but the version is not supported. Upgrade Laravel to the latest minor version"* then you can update by running the following command:

    ```shell theme={null}
    composer update laravel/framework
    ```
  </Tab>

  <Tab title="Symfony">
    Laravel Cloud requires Symfony 7.4 LTS or 8.x. Ensure your `composer.json` specifies a compatible version and that your `composer.lock` is up to date:

    ```shell theme={null}
    composer update symfony/framework-bundle
    ```
  </Tab>

  <Tab title="Next.js">
    Laravel Cloud supports Node.js 20, 22, and 24, Bun 1.2, and Deno 2.2.6 for Next.js applications. If you're using Node.js, ensure your `package.json` specifies a compatible engine:

    ```json theme={null}
    {
      "engines": {
        "node": ">=20"
      }
    }
    ```

    Bun and Deno run on a fixed version, so no `engines` configuration is needed for those runtimes.
  </Tab>

  <Tab title="Nuxt">
    Laravel Cloud supports Node.js 20, 22, and 24, Bun 1.2, and Deno 2.2.6 for Nuxt applications. If you're using Node.js, ensure your `package.json` specifies a compatible engine:

    ```json theme={null}
    {
      "engines": {
        "node": ">=20"
      }
    }
    ```

    Bun and Deno run on a fixed version, so no `engines` configuration is needed for those runtimes.
  </Tab>
</Tabs>

### Deployment succeeds but serves no traffic

<Tabs>
  <Tab title="Next.js">
    Laravel Cloud's in-pod proxy routes traffic to your application on the port set by the `PORT` environment variable (`3000` by default, or the port you chose when creating the application). The default start command, `next start`, reads `PORT` automatically, so this works out of the box for most applications.

    If you've overridden the start command with a custom server (for example, a `server.js` file using Express), the build can succeed even if that server listens on a different, hardcoded port. Laravel Cloud has no way to detect this, so the deployment goes live without routing any traffic to your application.

    Make sure your custom server reads the `PORT` environment variable rather than hardcoding a port number.
  </Tab>

  <Tab title="Nuxt">
    Laravel Cloud starts Nuxt applications with Nitro's default `node-server` preset (`.output/server/index.mjs`). If your `nuxt.config` still sets a host-specific `nitro.preset` (for example, `vercel`, `netlify`, or `cloudflare`) left over from a previous provider, or a `NITRO_PRESET` environment variable is set, Nitro builds output for that host instead (such as `.vercel/output`). The build completes without error, but Laravel Cloud has no way to serve that output, so the deployment goes live without routing any traffic to your application.

    Remove the `nitro.preset` option and any `NITRO_PRESET` environment variable so Nitro can auto-detect the `node-server` preset.
  </Tab>
</Tabs>