CI integration

Keep your project and pipeline config files in your repository and let GitHub Actions manage them. Open a pull request to preview the planned changes as a comment, then apply them automatically when the pull request merges. The workflow uses path filters so unrelated changes do not allocate a runner. YAML anchors define each config file path once and reuse it in the pull request and push filters. Two jobs cover projects and pipelines. Only the job for the current event runs:

Plan on pull request — shallow-fetches the comparison commit, runs ravion ... config apply --dry-run for each changed resource, and posts every plan in a single, updating PR comment.
Apply on merge — shallow-fetches the comparison commit and runs ravion ... config apply for each changed resource when the branch merges into your default branch.

Authenticate in CI

The CLI reads a service-account API key from the RAVION_API_KEY environment variable.

Create a service-account API key

Create a service account for CI and an API key for it. See ravion service-account and ravion api-key.

Store the key as a repository secret

In your GitHub repository, go to Settings → Secrets and variables → Actions and add a secret named RAVION_API_KEY with the API key value.

Add the workflow

Copy the prompt below into your coding agent to add and configure the GitHub action.

Discover your Ravion config files and add the CI workflow.

Open in Cursor

Create .github/workflows/ravion.yml. Define each project or pipeline as a contiguous indexed ID/file pair. Anchor every *_FILE value and reuse those aliases in ravion_paths, so each config file path appears once. Set RAVION_CLI_VERSION to the CLI release you want CI to use. Leave RAVION_AUTOAPPROVE as "false" to require manual approval of stack change pipeline runs in the Ravion dashboard, or set it to "true" to auto-approve project applies.

.github/workflows/ravion.yml

name: Ravion config

env:
  RAVION_API_KEY: ${{ secrets.RAVION_API_KEY }}
  RAVION_AUTOAPPROVE: "false"
  RAVION_CLI_VERSION: "0.1.6"
  # Keep indexes contiguous within each resource type.
  RAVION_PROJECT_1_ID: proj_3AV4cGr0t841Bstn4swCCrHrgly
  RAVION_PROJECT_1_FILE: &ravion_project_1_file packages/web/ravion.yaml
  RAVION_PROJECT_2_ID: proj_1CV4cGr0t841Bstn4swCCrHrgh7
  RAVION_PROJECT_2_FILE: &ravion_project_2_file packages/api/ravion.yaml
  RAVION_PIPELINE_1_ID: pipe_8Kd2mZq0t41Bstn4swCCrHrAa9
  RAVION_PIPELINE_1_FILE: &ravion_pipeline_1_file ravion-pipeline.yaml

on:
  pull_request:
    paths: &ravion_paths
      - *ravion_project_1_file
      - *ravion_project_2_file
      - *ravion_pipeline_1_file
  push:
    branches:
      - main
    paths: *ravion_paths

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - &list_changed_resources
        id: list
        name: List changed resources
        env:
          BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
          HEAD: ${{ github.sha }}
        run: |
          all_changed=false
          if [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
            all_changed=true
          else
            if ! git cat-file -e "$BASE^{commit}" 2> /dev/null; then
              git fetch --no-tags --depth=1 origin "$BASE"
            fi
            git diff --name-only "$BASE" "$HEAD" > changed.txt
          fi

          resources='[]'
          configured=0
          for resource in project:RAVION_PROJECT pipeline:RAVION_PIPELINE; do
            kind=${resource%%:*}
            prefix=${resource#*:}
            i=1
            while true; do
              id_var="${prefix}_${i}_ID"
              file_var="${prefix}_${i}_FILE"

              if [[ ! -v $id_var && ! -v $file_var ]]; then
                break
              fi
              if [[ ! -v $id_var || ! -v $file_var ]]; then
                echo "$kind $i must define both $id_var and $file_var" >&2
                exit 1
              fi

              configured=$((configured + 1))
              id="${!id_var}"
              file="${!file_var}"
              changed=$all_changed
              if [ "$changed" = false ]; then
                while IFS= read -r changed_file; do
                  if [ "$changed_file" = "$file" ]; then
                    changed=true
                    break
                  fi
                done < changed.txt
              fi

              if [ "$changed" = true ]; then
                resources=$(jq -cn \
                  --argjson current "$resources" \
                  --arg kind "$kind" \
                  --arg id "$id" \
                  --arg file "$file" \
                  '$current + [{kind: $kind, id: $id, file: $file}]')
              fi

              i=$((i + 1))
            done
          done

          if [ "$configured" -eq 0 ]; then
            echo "At least one Ravion project or pipeline must be configured" >&2
            exit 1
          fi

          echo "resources=$resources" >> "$GITHUB_OUTPUT"

      - name: Install the Ravion CLI
        if: steps.list.outputs.resources != '[]'
        run: curl -fsSL "https://github.com/flightcontrolhq/cli/releases/download/v${RAVION_CLI_VERSION}/install.sh" | sh

      - name: Build plan comment
        if: steps.list.outputs.resources != '[]'
        id: plan
        env:
          RESOURCES: ${{ steps.list.outputs.resources }}
        run: |
          {
            echo 'body<<BODY_EOF'
            echo '<!-- ravion-plan -->'
            echo '## Ravion planned changes'
            echo

            while read -r resource; do
              kind=$(jq -r '.kind' <<< "$resource")
              id=$(jq -r '.id' <<< "$resource")
              file=$(jq -r '.file' <<< "$resource")
              name="$id"
              label="Pipeline"

              if [ "$kind" = project ]; then
                label="Project"
                name=$(ravion project get "$id" --json 2> /dev/null | jq -r '.name // empty') || true
                name=${name:-$id}
              fi

              echo "### [$name](https://app.ravion.com/go/$id)"
              echo
              echo "$label: \`$file\`"
              echo
              plan_file=$(mktemp)
              if [ "$kind" = project ]; then
                NO_COLOR=1 ravion project config apply "$id" --file "$file" --dry-run > "$plan_file" 2>&1 || true
              else
                NO_COLOR=1 ravion pipeline config apply "$id" --file "$file" --dry-run > "$plan_file" 2>&1 || true
              fi
              echo '```diff'
              cat "$plan_file"
              echo '```'
              echo
            done < <(jq -c '.[]' <<< "$RESOURCES")

            echo 'BODY_EOF'
          } >> "$GITHUB_OUTPUT"

      - name: Comment the plan on the PR
        if: steps.list.outputs.resources != '[]'
        uses: actions/github-script@v7
        with:
          script: |
            const marker = '<!-- ravion-plan -->';
            const body = ${{ toJSON(steps.plan.outputs.body) }};
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });
            const existing = comments.find((c) => c.body.includes(marker));
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body,
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body,
              });
            }

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - *list_changed_resources

      - name: Install the Ravion CLI
        if: steps.list.outputs.resources != '[]'
        run: curl -fsSL "https://github.com/flightcontrolhq/cli/releases/download/v${RAVION_CLI_VERSION}/install.sh" | sh

      - name: Apply changes
        if: steps.list.outputs.resources != '[]'
        env:
          RESOURCES: ${{ steps.list.outputs.resources }}
        run: |
          while read -r resource; do
            kind=$(jq -r '.kind' <<< "$resource")
            id=$(jq -r '.id' <<< "$resource")
            file=$(jq -r '.file' <<< "$resource")

            if [ "$kind" = project ]; then
              autoapprove_args=()
              if [ "$RAVION_AUTOAPPROVE" = "true" ]; then
                autoapprove_args=(--autoapprove)
              fi
              ravion project config apply "$id" --file "$file" "${autoapprove_args[@]}"
            else
              ravion pipeline config apply "$id" --file "$file"
            fi
          done < <(jq -c '.[]' <<< "$RESOURCES")

GitHub leaves a path-filtered workflow’s check pending when the workflow is configured as a required status check but none of its paths match. Keep this workflow optional, or use a separate always-running check for branch protection.

RAVION_AUTOAPPROVE: "true" makes project applies approve supported stack change pipeline runs without a manual gate. Removing a module instance still runs a Terraform destroy. Keep it "false" if you want a human to approve runs in the Ravion dashboard. It applies to projects only; pipeline applies always create a new pipeline version.

In CI the CLI isn’t attached to a terminal, so its output is already plain text. The plan step also sets NO_COLOR=1 to strip any ANSI color codes before the output goes into the PR comment.

Introduction

Use cases

Concepts

Config as code

Migrate

Modules

Pipelines

Guides

Module definitions

Authenticate in CI

Add the workflow

Next steps

Project config file

Pipeline config file

​Authenticate in CI

​Add the workflow

​Next steps

Project config file

Pipeline config file

Authenticate in CI

Add the workflow

Next steps