Replicated CLI project configuration

The .replicated file is a per-project configuration file that the Replicated CLI uses. Place this file at the root of your project repository. It tells the CLI which application, Helm charts, Kubernetes manifests, and preflight checks belong to this project.

When you run commands like replicated release create without explicit flags, the CLI searches for this file in the current directory. It continues searching upward through parent directories.

The create-release GitHub action also reads this file, so the same .replicated file can drive releases from your local machine and from CI. See Use with the create-release GitHub action.

replicated release lint uses .replicated only when the release validation v2 feature flag is active or when the REPLICATED_RELEASE_VALIDATION_V2 environment variable is set to 1.

File location and name

Place the file at the root of your project. The CLI searches from the current working directory up through parent directories. It accepts either of these names:

.replicated
.replicated.yaml

What it configures

The .replicated file configures the following:

Application identity: which Replicated app this project belongs to
Charts: Helm charts to package as part of a release
Manifests: raw Kubernetes YAML files to include in a release
Preflights: preflight check specs to validate before install
Linting: local lint tool configuration and version pinning

Field reference

`appSlug` (string, optional)

The slug of your Replicated application. Commands that need to know which app to operate on, such as replicated release create, use this field. You can also provide this with the --app flag or the REPLICATED_APP environment variable.

appSlug: "my-application"

`appId` (string, optional)

The UUID of your Replicated application. Alternative to appSlug. If both are present, the CLI prefers appSlug.

appId: "12345678-1234-1234-1234-123456789abc"

`charts` (list, optional)

Helm charts to package when creating a release. Each entry is a chart with the following fields:

Field	Type	Required	Description
`path`	string	Yes	Path to the chart directory. Can be a glob pattern. Resolved relative to the `.replicated` file.
`chartVersion`	string	No	Override the chart version.
`appVersion`	string	No	Override the application version.

charts:
  - path: ./chart
  - path: ./charts/backend
    chartVersion: "1.2.3"
    appVersion: "v2.0.0"

`manifests` (list of strings, optional)

Glob patterns that match Kubernetes manifest YAML files to include in the release. Resolve these patterns relative to the .replicated file.

manifests:
  - ./manifests/*.yaml
  - ./crds/**/*.yaml

`preflights` (list, optional)

Preflight check specifications to lint and validate. Each entry has the following fields:

Field	Type	Required	Description
`path`	string	Yes	Path to the preflight spec file.
`chartName`	string	No	Explicit chart name to associate with this preflight.
`chartVersion`	string	No	Explicit chart version. Provide this together with `chartName`.

preflights:
  - path: ./preflight.yaml
  - path: ./preflights/ha-checks.yaml
    chartName: my-app
    chartVersion: "1.0.0"

`promoteToChannelNames` (list of strings, optional)

Channels to promote a new release to. The create-release GitHub action promotes to the first channel in the list when you don't set its promote-channel input. The replicated release create command doesn't use this field. To promote from the CLI, use the --promote flag.

promoteToChannelNames:
  - Unstable

`repl-lint` (object, optional)

Configuration for the local linting engine. This controls which linters run and which tool versions to use.

Field	Type	Description
`version`	integer	Lint config schema version. Defaults to `1`.
`linters`	object	Toggle individual linters on or off.
`tools`	map	Pin tool versions (e.g. `helm: "3.14.4"`). Defaults to `"latest"`.

Linter configuration

Each linter in linters supports a disabled boolean:

repl-lint:
  version: 1
  linters:
    helm:
      disabled: false        # on by default
    preflight:
      disabled: false        # on by default
    support-bundle:
      disabled: false        # on by default
    embedded-cluster:
      disabled: true         # off by default (opt-in)

The kots linter is parsed by the config but is not currently implemented. Enabling it has no effect.

The embedded-cluster linter also supports:

Field	Type	Description
`disable-checks`	list of strings	Checker IDs to skip. Defaults to `["helmchart-archive", "ecconfig-helmchart-archive"]`.
`binary-path`	string	Path to a custom embedded-cluster binary.

Tool version pinning

You can pin the versions of external tools that the linters use:

repl-lint:
  tools:
    helm: "3.14.4"
    preflight: "latest"
    support-bundle: "latest"

Versions must be either a semantic version (1.2.3 or v1.2.3) or the string latest.

The embedded-cluster linter discovers its version from the manifests instead of the tools map. Setting it in .replicated has no effect.

App resolution precedence

When a command needs to know which app to target, it resolves the value in this order:

--app flag
REPLICATED_APP environment variable
.replicated file (appSlug or appId)
Cached default app from replicated default app <slug>

Monorepo support

If you have a monorepo with multiple apps, you can place a .replicated file in each app subdirectory. The CLI searches upward from the current working directory and merges all found configuration files:

Scalar fields (appSlug, appId): child overrides parent.
Resource arrays (charts, preflights, manifests): accumulate from all levels.
repl-lint: child overrides parent settings.

This lets you define common settings at the repo root and app-specific settings in subdirectories.

Examples

Minimal Helm-only project

appSlug: "my-helm-app"
charts:
  - path: ./chart

KOTS manifests project

appSlug: "my-kots-app"
manifests:
  - ./manifests/*.yaml
  - ./crds/**/*.yaml

Multi-chart project with linting

appSlug: "my-platform"
charts:
  - path: ./charts/api
  - path: ./charts/worker
manifests:
  - ./manifests/*.yaml
  - ./configmaps/*.yaml
preflights:
  - path: ./preflights/cluster-checks.yaml
    chartName: api
    chartVersion: "1.0.0"
repl-lint:
  version: 1
  linters:
    helm:
      disabled: false
    preflight:
      disabled: false
    support-bundle:
      disabled: true

Monorepo root configuration

# At repo root: .replicated
repl-lint:
  version: 1
  linters:
    helm:
      disabled: false

# At apps/frontend/.replicated
appSlug: "frontend-app"
charts:
  - path: ./chart
manifests:
  - ./manifests/*.yaml

# At apps/backend/.replicated
appSlug: "backend-app"
charts:
  - path: ./chart
manifests:
  - ./manifests/*.yaml

Use with the create-release GitHub action

The create-release action in replicatedhq/replicated-actions reads .replicated when you don't set its chart or yaml-dir input. This lets you keep your app, chart, and manifest settings in one file instead of repeating them as workflow inputs. This behavior is available in v1.26.0 and later, including the v1 tag.

The action searches for the file starting from the root of the checked-out repository and continuing upward. It uses the following fields:

appSlug, when the app-slug input isn't set. The action doesn't use appId, so set appSlug or the app-slug input.
charts. The action runs helm dependency update and helm package for each chart, so Helm must be available on the runner.
manifests.
promoteToChannelNames. The action promotes to the first channel in the list when the promote-channel input isn't set.

Inputs you set in the workflow take precedence over the file. If you set chart or yaml-dir, the action doesn't read .replicated at all.

The following workflow step creates a release using only the .replicated file at the root of the repository:

steps:
  - uses: actions/checkout@v4
  - uses: replicatedhq/replicated-actions/create-release@v1
    with:
      api-token: ${{ secrets.REPLICATED_API_TOKEN }}

note

Because the action starts its search at the repository root, it doesn't find .replicated files in subdirectories. In a monorepo with a file per app, set the app-slug and chart or yaml-dir inputs for each app instead.

Create a configuration file

Run the interactive initialization command to generate a .replicated file for your project:

replicated config init

For non-interactive environments (e.g., CI):

replicated config init --non-interactive

File location and name​

What it configures​

Field reference​

appSlug (string, optional)​

appId (string, optional)​

charts (list, optional)​

manifests (list of strings, optional)​

preflights (list, optional)​

promoteToChannelNames (list of strings, optional)​

repl-lint (object, optional)​

Linter configuration​

Tool version pinning​

App resolution precedence​

Monorepo support​

Examples​

Minimal Helm-only project​

KOTS manifests project​

Multi-chart project with linting​

Monorepo root configuration​

Use with the create-release GitHub action​

Create a configuration file​

On this page