# Deploy file

Source: https://docs.fortrabbit.com/platform/deployment/deploy-file
Created: 2026-09-17

> A deploy file stores deployment settings as code in the Git repository, as an alternative to configuring them in the dashboard or by API.


New feature. The format and behavior described here may still change.

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`.



```yml [.fortrabbit/deploy.yml]
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:



```json [.fortrabbit/deploy.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.

| Key                               | Type                 | Default when left out | Dashboard setting                                                            |
| --------------------------------- | -------------------- | --------------------- | ---------------------------------------------------------------------------- |
| `apiVersion`                      | `1.0`                | required              | –                                                                            |
| `build.buildCommands`             | list of strings      | no commands           | [Build commands](/platform/deployment/build-commands)             |
| `build.postDeployCommands`        | list of strings      | no commands           | [Post deploy commands](/platform/deployment/post-deploy-commands) |
| `build.cachedDirectories`         | list of strings      | nothing cached        | [Cached directories](/platform/deployment/cached-directories)     |
| `distribution.gitSourceDirectory` | string               | repository root       | [Git source directory](/platform/deployment/git-source-directory) |
| `distribution.strategy`           | `merge` or `replace` | `replace`             | [Deployment strategy](/platform/deployment/strategy)              |
| `distribution.excludePatterns`    | list of strings      | nothing excluded      | [Exclude patterns](/platform/deployment/exclude-patterns)         |
| `distribution.replacePatterns`    | list of strings      | nothing deleted       | [Replace patterns](/platform/deployment/replace-patterns)         |

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.

Without `strategy` the deployment uses `replace`, also when the dashboard was set to `merge` before. The dashboard shows `replace` in that case. Add `excludePatterns` for files that must survive a deployment, such as user uploads.

## 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](/platform/deployment/trigger), the [deploy hook](/platform/deployment/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.

---

- [Deployment intro](/platform/deployment/intro)
- [Deployment strategy](/platform/deployment/strategy)
- [Software templates](/platform/concepts/software-templates)