Deploy file

The deploy file is a configuration file in the Git repository. It describes how an environment is deployed: which commands run during the build and how the build result reaches the environment. It replaces the deployment settings in the dashboard, so changes to them are versioned and reviewed together with the code.

# File location

The deploy file lives in the .fortrabbit directory in the root of the repository. It is recognized under one of these names, in this order:

• .fortrabbit/deploy.yml
• .fortrabbit/deploy.yaml
• .fortrabbit/deploy.json

Only the first file found is used.

# Format

The deploy file is a YAML or JSON mapping. It needs an apiVersion and groups the settings into two sections: build and distribution.

apiVersion: 1.0
build:
  buildCommands:
    - composer install --no-dev --prefer-dist --no-interaction
    - npm ci && npm run build
  postDeployCommands:
    - php artisan optimize:clear
  cachedDirectories:
    - bootstrap/cache
distribution:
  gitSourceDirectory: web
  strategy: replace
  excludePatterns:
    - storage

The same configuration as JSON:

{
  "apiVersion": 1.0,
  "build": {
    "buildCommands": ["composer install --no-dev --prefer-dist --no-interaction", "npm ci && npm run build"],
    "postDeployCommands": ["php artisan optimize:clear"],
    "cachedDirectories": ["bootstrap/cache"]
  },
  "distribution": {
    "gitSourceDirectory": "web",
    "strategy": "replace",
    "excludePatterns": ["storage"]
  }
}

# Schema

All keys are optional except apiVersion. A key that is left out falls back to the default in this table, not to the value in the dashboard.

A file that breaks one of these rules is invalid:

• build and distribution must be mappings. Other top-level keys and unknown keys inside the sections are not allowed.
• Strings must not be empty. Lists may be empty ([]), but their entries must not.
• replacePatterns requires strategy: merge. With replace everything is replaced, so there is nothing to delete beforehand.
• excludePatterns requires strategy: replace or no strategy. With merge nothing is deleted, so there is nothing to keep.

# Deploy file and dashboard

As soon as a deploy file is found on the deployed branch, it is the only source for the settings listed in the schema:

• Dashboard settings disabled — the deployment settings page of the environment shows the values from the file with a link to it. The settings from the schema can no longer be edited in the dashboard.
• File used for deployments — every deployment reads the deploy file from the commit it deploys. Changing a setting means a commit and a push.
• Dashboard values kept — the values saved in the dashboard are not overwritten. They stay stored, unused while the file exists.
• Other settings stay in the dashboard — the Git branch, the deployment permission, the deployment trigger, the deploy hook, the PHP version and the Node.js version are not part of the deploy file.

When creating a new app, the dashboard checks the selected branch for a deploy file. If one is found, the steps for deployment and post deploy commands are skipped.

# Invalid deploy file

An invalid deploy file fails the deployment before anything is built. The code in the environment stays unchanged. The log of the failed deployment names the file and the problem: the line for a syntax error, the key for a wrong value, and the position for a wrong list entry. Fix the file and push again.

The dashboard settings are not used as a fallback.

# Removing the deploy file

Delete the deploy file from the repository and push. The next deployment uses the settings saved in the dashboard again, and they become editable there.