Manage code deployments with scripts, queues, and CI tools
.env
file to configure settings such as databases and caches. You can create and edit your Environment file within the Forge site’s management dashboard.
.env.example
file, Forge will automatically copy this and replace some of the settings to match your server’s database settings. An empty .env.example
could result in an empty environment file on the first deploy.site:manage-environment
permission. Without this permission, Forge will not display the contents of the environment file to circle members.
LARAVEL_ENV_ENCRYPTION_KEY
environment variable during deployment, allowing you to add the env:decrypt
Artisan command to your deployment script without explicitly setting the --key
option:
git pull
commandphp artisan migrate
command (if your application contains an artisan
file).env
variables available to your deploy script by checking the “Make .env variables to deploy script” checkbox below the Deploy Script panel. When enabled, Forge will automatically inject the variables in your site’s .env
file into the deploy script, allowing them to be accessed like any normal Bash variable:
php
will always point to the active version of PHP used on the CLI. If you need to use a different version of PHP, you must use phpx.x
where x.x
reflects on the version used (e.g. php8.4
) when invoking PHP commands.
The deployment script for newly created sites uses the $FORGE_PHP
environment variable. This environment variable will always contain the current PHP binary configured for the site, so no additional changes are needed to your deployment script when using this variable and switching your site’s PHP version.
Key | Description |
---|---|
FORGE_COMPOSER | The path to the Composer installation. |
FORGE_CUSTOM_DEPLOY | Whether the deployment was triggered with a custom deployment trigger request. |
FORGE_DEPLOY_AUTHOR | The author of the commit. |
FORGE_DEPLOY_COMMIT | The Git hash of the commit being deployed. |
FORGE_DEPLOY_MESSAGE | The Git commit message. |
FORGE_DEPLOYMENT_ID | The Forge assigned ID of this deployment. |
FORGE_MANUAL_DEPLOY | Whether the deploy was triggered by clicking “Deploy Now”. |
FORGE_PHP_FPM | The PHP-FPM process name that is being used by Forge. |
FORGE_PHP | The php binary that is being used by the Forge site or server. |
FORGE_QUICK_DEPLOY | Whether the deploy was triggered by a source control provider webhook. |
FORGE_REDEPLOY | Whether this is a re-deployed commit. |
FORGE_SERVER_ID | The ID of the Forge server that is being deployed to. |
FORGE_SITE_BRANCH | The name of the branch that is being deployed. |
FORGE_SITE_ID | The ID of the Forge site that is being deployed to. |
FORGE_SITE_PATH | The root of the deployment path, e.g. /home/forge/mysite.com |
FORGE_SITE_USER | The name of the user deploying the site. |
FORGE_
. Please do not use this “namespace” when defining your own environment variables.GET
or POST
request to the “Deployment Trigger URL” displayed in your site’s details.
Although you can refresh the site token at any time, you will need to update any services which are using this URL after refreshing the token.
Additional data may be passed to your deployment script via query parameters passed to the deployment trigger URL. For example, when passing the following query parameters ?token=abc1234&env=staging
, Forge will automatically inject a custom FORGE_VAR_ENV
variable that will evaluate to "staging"
.
There are 4 reserved parameters you may use to pass Forge information when triggering a deployment:
forge_deploy_branch
: The branch that contains the commit. Forge will only trigger a deployment if the branch matches the site’s currently deployed branch.forge_deploy_commit
: The hash of the commit. This will be visible in the “Deployments” table and be available as the FORGE_DEPLOY_COMMIT
environment variable in your deploy script.forge_deploy_author
: The author of the commit. This will be visible in the “Deployments” table and be available as the FORGE_DEPLOY_AUTHOR
environment variable in your deploy script.forge_deploy_message
: The commit message. This will be available as the FORGE_DEPLOY_MESSAGE
environment variable in your deploy script.forge deploy
command in your CI platform’s deployment pipeline.
In order to authenticate with Forge from your CI platform, you will need to add a FORGE_API_TOKEN
environment variable to your CI build environment. You may generate an API token in your Forge API settings dashboard. In addition, your CI platform will need SSH Access to your server.
main
branch:
FORGE_API_TOKEN
environment variable to your “GitHub > Project Settings > Secrets” settings so that GitHub can authenticate with Forge while running actions.
SSH_PRIVATE_KEY
environment variable to your “GitHub > Project Settings > Secrets” settings so that GitHub can have SSH Access to your site’s server.
deploy.yml
file within the your-project/.github/workflows
directory. The file should have the following contents:
deploy.yml
file to fit your site’s deployment needs, as it may require a different PHP version or a library like npm
. Once you are done, commit and push the deploy.yml
file to the main
branch so GitHub Actions can run the first deployment job.main
branch:
FORGE_API_TOKEN
environment variable to your “Project > Project Settings > Secrets” settings so that Chipper can authenticate with Forge.
SSH_PRIVATE_KEY
environment variable to your “Project > Project Settings > Secrets” settings so that Chipper has SSH access to your site’s server.
.chipperci.yml
file. The file will look something like this:
.chipperci.yml
file further to fit your needs. Once you are done, commit and push to the main
branch so Chipper CI can deploy your site.laravel_forge_telegram_bot
. Finally, copy the /start
command, provided by Forge under the Telegram Deployment Notifications section, and paste it into the chat.
If you wish to change the group that Forge messages, you should disable Telegram notifications and then follow the above steps again to reactive notifications.
site:manage-deploys
permission.