reoclo.yml reference

A reoclo.yml file sets the build, deploy, and CI behavior for one application. Reoclo reads the file from your repository, instead of only the dashboard.

Where the file lives

Reoclo reads the file from one of two locations.

<base_directory>/reoclo.yml, in the application’s base directory. This file needs no app: key. Its location already identifies the application.
ci/reoclo/<label>.yml, one file for each application. Each file needs a top-level app: selector, so Reoclo knows which application it configures.

Set app.slug or app.base_directory in a ci/reoclo/<label>.yml file. Set one of the two fields. Reoclo rejects a file that sets neither.

Reoclo reads the file at the commit it deploys. A deployment always uses the version of the file from its own commit, never a cached copy.

The setup wizard’s repository scan finds these files at the same two locations. If your config lives somewhere else, use Add a config file by path on the scan step to point the scan at it.

Never put a secret value in reoclo.yml. Anyone with read access to your repository can read the file. Store secrets as environment variables, or in the Reoclo secrets manager, instead.

Stacks

For a stack, the compose file is the source of truth for build and deploy settings. The source, build, deploy, and health_check sections do not apply to stack members.

One key does apply: ci.require_checks. Reoclo reads it from every member’s reoclo.yml and applies the result to the whole stack. When the files disagree, an explicit true wins. When no member file sets the key, the stack’s own Require CI checks toggle applies. See Wait for CI before a deployment.

version

Key	Type	Default
`version`	integer, `1` or `2`	`1`

version sets the pipeline spec format. Set version: 2 to define custom stages.

source

source sets where Reoclo gets your application code.

Key	Type	Default
`source.type`	`git` or `image`	`git`
`source.repository_id`	string	not set
`source.branch`	string	`main`
`source.base_directory`	string	`.`
`source.clone_depth`	integer, 1 to 100	`1`
`source.image`	string	not set
`source.image_command`	string	not set
`source.registry_credential_id`	string	not set

Reoclo binds source.repository_id and source.registry_credential_id from the application’s dashboard configuration. A repository-hosted reoclo.yml file does not set these two fields.

Set source.image when source.type is image. Set build.type to docker_image too. An image source always builds from a registry image.

build

build sets how Reoclo builds your application.

Key	Type	Default
`build.type`	`dockerfile`, `docker_image`, or `docker_compose`	`dockerfile`
`build.dockerfile_path`	string	`Dockerfile`
`build.build_context`	string	`.`
`build.build_args`	map of string to string	empty
`build.target_stage`	string	not set
`build.compose_file_path`	string	`docker-compose.yml`
`build.compose_service`	string	not set
`build.compose_content`	string	not set

Reoclo rejects build.compose_content in a repository-hosted file. Set build.compose_file_path to a file in your repository instead.

deploy

deploy sets how Reoclo runs your application’s container.

Key	Type	Default
`deploy.server_id`	string	not set
`deploy.port_mappings`	list of port mappings	one mapping, container port `8080`
`deploy.replicas`	integer, 1 to 10	`1`
`deploy.resource_limits.cpu_cores`	number, 0.1 to 16	`1.0`
`deploy.resource_limits.memory_mb`	integer, 64 to 32768	`512`
`deploy.use_docker_secrets`	boolean	`false`
`deploy.health_check_port`	integer	not set

Reoclo binds deploy.server_id from the application’s dashboard configuration. A repository-hosted reoclo.yml file does not set this field.

Each entry in deploy.port_mappings has these fields:

Key	Type	Default
`container_port`	integer, 1 to 65535	`8080`
`host_port`	integer	not set
`protocol`	string	`tcp`
`label`	string	empty

When host_port is not set, Reoclo publishes the container port as the host port. Set host_port when that port is already in use on the server.

health_check

health_check sets the check Reoclo runs against a new container, before Reoclo replaces the old one.

Key	Type	Default
`health_check.type`	`none`, `http`, `tcp`, or `command`	`none`
`health_check.http_path`	string	not set
`health_check.http_method`	string	`GET`
`health_check.command`	string	not set
`health_check.interval_seconds`	integer, 5 to 300	`30`
`health_check.timeout_seconds`	integer, 1 to 120	`10`
`health_check.retries`	integer, 1 to 20	`3`
`health_check.start_period_seconds`	integer, 0 to 300	`10`

See Deployment Configuration for what makes a good health check.

ci

ci sets how Reoclo reports a deployment to your git provider, and whether a push waits for CI.

ci:
  report_status: true        # post a commit status (reoclo/deploy/<app>) for each deployment
  report_deployment: true    # on GitHub, also create a Deployment in the Environments panel
  auto_deploy_branches: [main]
  require_checks: true       # wait for every check on the commit before a push deploys

Key	Type	Default
`ci.report_status`	boolean	`true`
`ci.report_deployment`	boolean	`true`
`ci.auto_deploy_branches`	list of strings	`[main]`
`ci.require_checks`	boolean, or not set	not set

When ci.require_checks is not set, the application’s dashboard setting applies. Set ci.require_checks to true or false to override the dashboard setting.

For a repo-sourced spec, the copy of reoclo.yml on the repository default branch decides which branches can auto-deploy. A pushed branch cannot add itself to ci.auto_deploy_branches in its own copy of the file. Reoclo refreshes the stored copy on each push to the default branch, so add the branch there first. The build and deploy steps still come from the file on the branch that deploys.

See Wait for CI before a deployment and Deployment Status on GitHub and Gitea.

branches

branches overrides source, build, deploy, or health_check for one branch. Reoclo merges each override into the defaults set earlier in this page. Reoclo does not override ci for a branch.

branches:
  staging:
    deploy:
      server_id: 00000000-0000-0000-0000-000000000000

Key	Type	Default
`branches.<name>.source`	map, same fields as `source`	empty
`branches.<name>.build`	map, same fields as `build`	empty
`branches.<name>.deploy`	map, same fields as `deploy`	empty
`branches.<name>.health_check`	map, same fields as `health_check`	empty

stages

stages replaces the default pipeline with a custom set of steps. Set version: 2 to use stages.

Key	Type	Default
`stages`	map of stage name to stage definition	not set

When stages is not set, Reoclo runs its default pipeline: precheck, clone, build, deploy, health check, then cleanup.

Each stage definition has these fields:

Key	Type	Default
`type`	`builtin` or `command`	`builtin`
`builtin`	`precheck`, `clone`, `build`, `deploy`, `health_check`, or `cleanup`	not set
`command`	string	not set
`needs`	list of stage names	empty
`timeout_seconds`	integer, 10 to 3600	`600`

Set builtin when type is builtin. Set command when type is command.

Reoclo does not run command stages yet. Set type: builtin for every stage today.

A pipeline holds at most 20 stages. Reoclo rejects a stages map that has a cycle in needs, or a needs entry that names a stage that does not exist.

Next Steps

Wait for CI before a deployment to gate a push deployment on passing checks
Deployment Status on GitHub and Gitea for what Reoclo posts back to your git provider
Deployment Configuration for the dashboard equivalent of these settings