Project config file

Define a project declaratively in .yaml, .jsonc, or .cue. The top-level environments[] array contains moduleInstances[], and modules reference each other with moduleGivenIdRef.

Example project config

A minimal ravion.yaml with a VPC, an ECS cluster, and a web service. Modules reference each other with moduleGivenIdRef.

ravion.yaml

project:
  givenId: demo
  name: Demo
environments:
  - givenId: production
    name: Production
    moduleInstances:
      - givenId: vpc
        name: VPC
        type: rvn-aws-network
        version: 0.1.0
        input:
          aws_account_id: ravion-prod
          aws_region: ca-central-1
          name: demo-production
          vpc_cidr: 10.0.0.0/16
          nat_gateway_enabled: true

      - givenId: ecs-cluster
        name: ECS Cluster
        type: rvn-ecs-cluster
        version: 0.1.2
        input:
          network:
            moduleGivenIdRef: vpc # Must be type rvn-aws-network
          name: demo-production
          fargate_enabled: true
          fargate_spot_enabled: true
          public_alb_enabled: true

      - givenId: web-app
        name: web-app
        type: rvn-ecs-web
        version: 0.5.0
        input:
          cluster:
            moduleGivenIdRef: ecs-cluster # Must be type rvn-ecs-cluster
          name: demo-production-web-app
          public_web_service_enabled: true
          build_type: dockerfile
          source_repo: my-org/my-repo
          source_base_path: "."
          dockerfile: Dockerfile
          container_port: 80
          health_check_path: /

Pull and apply

Store the config file in your repository and manage it with the CLI.

Create the project, if needed

ravion project create --given-id <project-id> --name "My project"

Pull the current config

Write the live project config to a file.

ravion project config pull <project-id> --file project.yaml

Pulling a .yaml, .jsonc, or .cue file adds an AI skill header, inline field comments, and quick links to the generated file. Plain .json does not support comments, so it omits these annotations.

Edit the file

Add or edit environments and add, edit, or remove module instances.

Removing a module instance from the config file will run the Terraform plan for the Terraform destroy action and then wait for manual approval. You’ll need to manually approve the destroy and then delete the module instance from the system.

Preview with a dry run

Validate the file and print the planned changes without applying them.

ravion project config apply <project-id> --file project.yaml --dry-run

Apply the changes

Apply the config to update the stored config and run the Terraform plan if needed.

ravion project config apply <project-id> --file project.yaml

Add --autoapprove to approve supported stack change pipeline runs without a manual gate.

Review and approve the stack run

Applying a config change starts a stack change pipeline run when the affected module has a Terraform stack. The stack run creates a Terraform plan and waits for manual approval before applying, unless you pass --autoapprove to an apply command that supports it.After the stack run starts, inspect the run and its Terraform results with these commands:

ravion pipeline run get <pipeline-run-id>
ravion pipeline run get-plan <pipeline-run-id>
ravion pipeline run get-apply <pipeline-run-id>
ravion logs pipeline-step <step-execution-id>

Integrate with CI

Commit the config file and let GitHub Actions plan changes on each pull request and apply them on merge.See CI integration.

Agent tips

Use these rules when an agent edits a project config file.

Required workflow

Check the project config schema before editing:

ravion project config schema

List available module definitions before adding a module:

ravion module definition list

Inspect the input schema before adding or editing a module instance:

ravion module schema <module-type> [version]

Preview every change before applying it:

ravion project config apply <project-id> --file ravion.yaml --dry-run

Apply only after the dry run is correct and approved:

ravion project config apply <project-id> --file ravion.yaml

Helpful hints

Pull the latest live config anytime with ravion project config pull <project-id> --file ravion.yaml.
Use --autoapprove only for supported stack changes that do not need a manual approval gate.
To iterate on one target, pass --environment-id, --environment-given-id, --module-instance-id, or --module-given-id.

Module editing rules

Treat the config file as the source of truth for the current task.
Preserve existing IDs, givenId values, module versions, and Ravion app links unless asked to change them.
Tailor recommended settings to the target environment.
Ask about important settings that cannot be inferred with high confidence.
Ask before production-impacting changes such as public access, deletion protection, backup retention, capacity, region, or networking exposure.

Do not

Copy module inputs from unrelated files or examples.
Invent fields that are not present in the CLI schema output.
Apply changes without a successful dry run first.

Schema reference

Use this reference when you author project config files or generate project configuration from another system. For a compact, machine-readable version, fetch https://api.ravion.com/projects/config/schema.md.

Legend

Notation	Meaning
`T[]`	Array of `T`
`map<string,T>`	Object keyed by strings with `T` values
`enum[a,b]`	One of the listed values
`A \| B`	One of several types
~template	Field accepts `<< ... >>` template expressions

ProjectConfig

User-authored project config file consumed by ravion projects config apply --file.

project

Project.ApplyProjectConfigProject

Project metadata to update before applying environment configuration.See: Project

environments

Project.ProjectConfigFileEnvironment[]

required

Environment configuration blocks to apply.See: Environment

Project

Writable project metadata accepted by project config apply.

string

Existing project ID. When provided, it must match the project in the route.

givenId

string

User-provided project identifier. When provided, it must match the project in the route.

name

string

description

string

Environment

Environment block authored in project config files.

string

Existing environment ID.

givenId

string

User-provided environment identifier.

name

string

description

string

moduleInstances

Project.ProjectConfigFileModuleInstance[]

required

See: ModuleInstance

ModuleInstance

Module instance shape authored in project config files.

string

Existing module instance ID. Non-empty IDs must resolve to an existing module.

givenId

string

User-provided unique identifier. Must be unique within environment.

name

string

description

string

type

string

Module type identifier.

version

string

Semantic module version string.

input

map<string,any | null>

Runtime module configuration input.

Module references

Use {moduleGivenIdRef: "..."} inside module input fields that reference another module.

Scope	Reference
Same environment	`{moduleGivenIdRef: "module"}`
Cross environment, same project	`{moduleGivenIdRef: "environment.module"}`
Cross project, same organization	`{moduleGivenIdRef: "project.environment.module"}`

Use givenId values for the project, environment, and module segments.

Introduction

Use cases

Concepts

Config as code

Migrate

Modules

Pipelines

Guides

Module definitions

Pull and apply

Agent tips

Required workflow

Helpful hints

Module editing rules

Do not

Schema reference

Legend

ProjectConfig

Project

Environment

ModuleInstance

Module references

​Pull and apply

​Agent tips

​Required workflow

​Helpful hints

​Module editing rules

​Do not

​Schema reference

​Legend

​ProjectConfig

​Project

​Environment

​ModuleInstance

​Module references

Pull and apply

Agent tips

Required workflow

Helpful hints

Module editing rules

Do not

Schema reference

Legend

ProjectConfig

Project

Environment

ModuleInstance

Module references