> ## Documentation Index
> Fetch the complete documentation index at: https://ravion-b90c0359-devin-1786804702-tf-policy-checks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project config file

> Manage a full Ravion project's configuration—environments, modules, and pipelines—from a single declarative YAML file in source control.

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

<Accordion title="Example project config">
  A minimal `ravion.yaml` with a VPC, an ECS cluster, and a web service. Modules reference each other with `moduleGivenIdRef`.

  ```yaml ravion.yaml theme={null}
  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: /
  ```
</Accordion>

## Pull and apply

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

<Steps>
  <Step title="Create or select the project">
    For a new project, create the project and write its draft config file:

    ```bash theme={null}
    ravion project create --given-id <project-id> --name "My project" --file ravion.yaml
    ```

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

    ```bash theme={null}
    ravion project config pull <project-id> --file ravion.yaml
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Edit the file">
    Add or edit environments and add, edit, or remove module instances.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Preview with a dry run">
    Validate the file and print the planned changes without applying them.

    ```bash theme={null}
    ravion project config apply <project-id> --file ravion.yaml --dry-run
    ```
  </Step>

  <Step title="Apply the changes">
    Apply the config to update the stored config and run the Terraform plan if needed.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Review and approve the stack run">
    Applying a config change starts a [stack change pipeline run](/modules/stack#stacks-change-through-pipelines) 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:

    ```bash theme={null}
    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:

    ```bash theme={null}
    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>
    ```
  </Step>

  <Step title="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](/config-as-code/ci-integration).
  </Step>
</Steps>

## 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

1. Check the project config schema before editing:

```bash theme={null}
ravion project config schema
```

2. List available module definitions before adding a module:

```bash theme={null}
ravion module definition list
```

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

```bash theme={null}
ravion module schema <module-type> [version]
```

4. Preview every change before applying it:

```bash theme={null}
ravion project config apply <project-id> --file ravion.yaml --dry-run
```

5. Apply only after the dry run is correct and approved:

```bash theme={null}
ravion project config apply <project-id> --file ravion.yaml
```

6. 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:

```bash theme={null}
# 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
```

7. 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](/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`.

<ResponseField name="project" type="Project.ApplyProjectConfigProject">
  Project metadata to update before applying environment configuration.

  See: [Project](#project)
</ResponseField>

<ResponseField name="environments" type="Project.ProjectConfigFileEnvironment[]" required>
  Environment configuration blocks to apply.

  See: [Environment](#environment)
</ResponseField>

## Project

Writable project metadata accepted by project config apply.

<ResponseField name="id" type="string">
  Existing project ID. When provided, it must match the project in the route.
</ResponseField>

<ResponseField name="givenId" type="string">
  User-provided project identifier. When provided, it must match the project in the route.
</ResponseField>

<ResponseField name="name" type="string" />

<ResponseField name="description" type="string" />

## Environment

Environment block authored in project config files.

<ResponseField name="id" type="string">
  Existing environment ID.
</ResponseField>

<ResponseField name="givenId" type="string">
  User-provided environment identifier.
</ResponseField>

<ResponseField name="name" type="string" />

<ResponseField name="description" type="string" />

<ResponseField name="moduleInstances" type="Project.ProjectConfigFileModuleInstance[]" required>
  See: [ModuleInstance](#moduleinstance)
</ResponseField>

## ModuleInstance

Module instance shape authored in project config files.

<ResponseField name="id" type="string">
  Existing module instance ID. Non-empty IDs must resolve to an existing module.
</ResponseField>

<ResponseField name="givenId" type="string">
  User-provided unique identifier. Must be unique within environment.
</ResponseField>

<ResponseField name="name" type="string" />

<ResponseField name="description" type="string" />

<ResponseField name="type" type="string">
  Module type identifier.
</ResponseField>

<ResponseField name="version" type="string">
  Semantic module version string.
</ResponseField>

<ResponseField name="input" type="map<string,any | null>">
  Runtime module configuration input.
</ResponseField>

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