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 or select the project

For a new project, create the project and write its draft config file:

ravion project create --given-id <project-id> --name "My project" --file ravion.yaml

For an existing project, write its live config to a file:

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

Creating or 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 ravion.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 ravion.yaml

Add --autoapprove to approve supported stack change pipeline runs without a manual gate.Add --description to set the description on every stack run the apply creates, for example --description "https://github.com/acme/app/pull/12" to link the runs to the pull request that changed the config. Without it, runs keep Ravion’s generated description.

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.The apply prints a PIPELINE_RUN_ID for every stack run it starts, plus the wait command for those runs. Follow a run with wait --watch instead of polling pipeline run get.The runs are listed in dependency order, so you can work through them one at a time: a run only starts once the runs it depends on succeed.Without --autoapprove, each run stops at its approval gate, so wait for that gate, review the plan, approve, then wait for the apply:

ravion pipeline run wait <pipeline-run-id> --until PENDING_APPROVAL --watch

ravion pipeline run get-plan <pipeline-run-id>
ravion pipeline run approve <pipeline-run-id>
ravion pipeline run wait <pipeline-run-id> --watch

With --autoapprove, wait for the run to finish, then inspect the Terraform results:

ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m

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. Never hand-write a ravion.yaml from memory. Generate it with ravion project create --file for a new project or ravion project config pull --file for an existing project so it carries the current header, comments, and links, then edit it.

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

After applying config, use ravion pipeline run wait <id> --watch instead of repeatedly polling pipeline run get. The apply output lists a PIPELINE_RUN_ID for every stack run it starts, followed by the exact wait command to run. Work through the commands in the printed order, which is dependency order:

# Runs stop for approval unless the apply passed --autoapprove
ravion pipeline run wait <pipeline-run-id> --until PENDING_APPROVAL --watch

# Autoapproved runs go straight through
ravion pipeline run wait <pipeline-run-id> --watch --timeout 30m

Follow application deployments the same way, with ravion deploy wait <deployment-id> --watch instead of polling deploy get.

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.
If a schema check, dry run, or apply fails unexpectedly, file it with ravion report bug "<what happened>" --command "<the command that failed>". Include the exact error text and the project, environment, and module instance IDs involved. See Report bugs and feedback.

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.
Poll ravion pipeline run get or ravion deploy get in a loop. Use the matching wait --watch command instead.

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

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

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.

string

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

string

Environment

Environment block authored in project config files.

string

Existing environment ID.

string

User-provided environment identifier.

string

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.

string

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

string

Module type identifier.

string

Semantic module version string.

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

Concepts

Config as code

Migrate

Modules

Pipelines

Guides

Troubleshooting

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