Creating Dynamic Deployments on Laravel Forge

In real-world development workflows, deployments are rarely “one size fits all.”

Many times, you need flexibility.

You don’t always want to run a full deployment — install dependencies, compile assets, optimize the application, run migrations, etc. Sometimes all you need is a quick git pull to ship a small fix or update a simple file without rebuilding the entire application.

For example:

• You fixed a typo in a Blade file.
• You updated a config value.
• You modified a text file or a single class.
• You changed something that doesn’t require node builds or composer updates.

Running a full deployment in these cases is unnecessary, slow, and may even cause downtime during heavy build steps.

This is where dynamic deployments come in.

Laravel Forge allows you to pass custom query parameters through the deployment hook URL — and these parameters automatically become environment variables inside your deployment script. With this feature, you can run different deployment workflows based on the parameter you send.

In this article, you’ll learn how to use this feature to switch between:

• Simple Deployment → only git pull
• Full Deployment → composer install, node build, migrations, cache optimizations, etc.

Let’s dive in.

Understanding Custom Deployment Hook Parameters

Laravel Forge automatically injects your custom query parameters into the deployment script using the FORGE_VAR_* format.

From the Forge documentation:

If you pass the query parameter &env=staging to the deployment hook URL, Forge will inject a FORGE_VAR_ENV variable into your deployment script that will evaluate to "staging".

This means you can pass any custom parameter and use it to control your deployment behavior.

Example deployment hook:

https://forge.laravel.com/servers/984512/sites/2935083/deploy/http?token=TOKEN&deploymentType=simple

Forge will turn this into:

FORGE_VAR_DEPLOYMENTTYPE="simple"

Real Use Case: Switch Between Simple and Full Deployments

Let’s say we want:

• deploymentType=simple → run only git pull
• deploymentType=full (or omitted) → run the full deployment

This gives us complete flexibility using a single script.

Step 1: Trigger the Deployment With a Parameter

For a simple deployment:

https://forge.laravel.com/actions/deploy/123456?deploymentType=simple

For a full deployment:

https://forge.laravel.com/actions/deploy/123456?deploymentType=full

If you omit the parameter entirely, your script can default to the full workflow.

Step 2: Handle the Parameter Inside the Deployment Script

Forge injects:

FORGE_VAR_DEPLOYMENTTYPE=”simple”

So modify your deployment script like this:

#!/usr/bin/env bash

# Normalize the input
DEPLOYMENT_TYPE=$(echo "$FORGE_VAR_DEPLOYMENTTYPE" | tr '[:upper:]' '[:lower:]')

echo "Deployment type: ${DEPLOYMENT_TYPE:-full}"

# --- SIMPLE DEPLOYMENT -----------------------------------
if [ "$DEPLOYMENT_TYPE" = "simple" ]; then
    echo "Running simple deployment..."

    git pull origin $FORGE_VAR_BRANCH || exit 1

    echo "Simple deployment completed."
    exit 0
fi

# --- FULL DEPLOYMENT -------------------------------------
echo "Running full deployment..."

git pull origin $FORGE_VAR_BRANCH || exit 1

composer install --no-interaction --prefer-dist --optimize-autoloader

php artisan migrate --force
php artisan optimize

# Uncomment if your app uses node builds
# npm install
# npm run build

echo "Full deployment completed."

How This Works

• Forge transforms custom query params into FORGE_VAR_* variables.
• You read them in Bash.
• Based on the value you choose, you select a deployment path.
• If deploymentType=simple, you skip heavy steps.
• Otherwise, you run the full deployment process.

This provides CI/CD-level flexibility without requiring you to modify Forge’s UI every time.

Additional Ideas Using Custom Parameters

You can build even more dynamic workflows:

Run migrations only when needed:

&migrate=true

Clear caches:

&clearCache=yes

Deploy a different branch:

&branch=develop

Enable maintenance mode during deploy:

&maintenance=on

Each becomes:

FORGE_VAR_MIGRATE
FORGE_VAR_CLEARCACHE
FORGE_VAR_BRANCH
FORGE_VAR_MAINTENANCE

And you can conditionally run those steps as well.

Security Considerations

Deployment hook URLs are sensitive. To protect them:

• Treat them as secrets.
• Regenerate the hook URL periodically.
• Limit where the URL is used (e.g., CI/CD).
• Optionally add a token=my-secret parameter and validate it in your script.

Conclusion

By passing custom query parameters to your Laravel Forge deployment hook URL, you can turn a simple trigger into a flexible deployment engine.

This allows you to:

• Deploy faster
• Reduce downtime
• Avoid unnecessary build steps
• Keep your deployment script clean and reusable
• Customize deployment behavior without modifying Forge settings

Whether you’re pushing a quick fix or rolling out a major update, this approach gives you full control with a simple URL parameter.