> ## Documentation Index
> Fetch the complete documentation index at: https://www.ravion.com/docs/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 the project, if needed">
    ```bash theme={null}
    ravion project create --given-id <project-id> --name "My project"
    ```
  </Step>

  <Step title="Pull the current config">
    Write the live project config to a file.

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

    <Note>
      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 project.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 project.yaml
    ```

    Add `--autoapprove` to approve supported stack change pipeline runs without a manual gate.
  </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.

    After the stack run starts, inspect the run and its Terraform results with these commands:

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

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

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

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