> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions integration

> Run CloudEval review in CI with the official composite action — access keys, report gates, PR comments, and artifacts.

Use the **[CloudEval GitHub Action](https://github.com/ganakailabs/cloudeval-action)** when you want CloudEval review results inside GitHub Actions without hand-rolling install and auth steps.

<Tip>
  Use the **[CloudEval GitHub App](https://github.com/apps/cloudeval-ai)** for repository sync into CloudEval. Use the **GitHub Action** for CI review, merge gates, PR comments, and report artifacts after a CloudEval project exists.
</Tip>

<Note>
  Want to see it before wiring your own repo? Inspect the [passing baseline demo PR](https://github.com/ganakailabs/cloudeval-azure-arm-review-example/pull/6) and the [risk regression demo PR](https://github.com/ganakailabs/cloudeval-azure-arm-review-example/pull/1) in the public Azure ARM review example.
</Note>

<Frame caption="Video walkthrough: automated pull-request review for infrastructure-as-code changes in GitHub.">
  <iframe src="https://www.youtube.com/embed/NCHq0AyEwAo" title="Automated review of pull-request on GitHub repo for Infrastructure-as-Code changes - CloudEval AI" width="100%" height="415" loading="lazy" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />
</Frame>

## Public example

Use [ganakailabs/cloudeval-azure-arm-review-example](https://github.com/ganakailabs/cloudeval-azure-arm-review-example) as a clean public reference repository. It contains nested ARM templates, `.cloudeval/config.yaml`, a ready-to-copy CloudEval review workflow, and long-lived demo pull requests:

| Demo PR                                                                                            | Expected check | What to inspect                                                                                                               |
| -------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [Passing baseline gates](https://github.com/ganakailabs/cloudeval-azure-arm-review-example/pull/6) | Green          | A passing review with baseline thresholds while the comment still shows CRITICAL posture, validation, cost, and report links. |
| [Risk regression](https://github.com/ganakailabs/cloudeval-azure-arm-review-example/pull/1)        | Red            | A risky IaC change with blocking gate failures and high-risk posture signals.                                                 |
| [Cost regression](https://github.com/ganakailabs/cloudeval-azure-arm-review-example/pull/2)        | Red            | Five-digit monthly cost estimate, resource cost drivers, and a failing monthly budget gate.                                   |
| [Security hardening](https://github.com/ganakailabs/cloudeval-azure-arm-review-example/pull/3)     | Red            | Security-focused remediation work that still fails until configured thresholds are satisfied.                                 |

Use the public PRs when you want to inspect the workflow without connecting Azure or uploading private source. Fork the repo, install the [CloudEval GitHub App](https://github.com/apps/cloudeval-ai) on the fork, create a CloudEval project from it, then add `CLOUDEVAL_ACCESS_KEY` and `CLOUDEVAL_PROJECT_ID` secrets. The workflow intentionally skips review until those secrets exist.

## What it does (and does not do)

The action runs on **your** workflow runner, installs the **CloudEval CLI** (unless you skip install), and calls the **same CloudEval API** as the browser and CLI using a **scoped access key** (`cev_…`).

It does **not** install the GitHub App, change repository settings, branch rules, or files on its own. It **can**:

* Run `cloudeval review` for the checked-out GitHub repository and linked CloudEval project.
* Fail a job when explicit `.cloudeval/config.yaml` `ci.gates` are not met.
* Attach **workflow artifacts** (JSON, summaries, downloaded reports).
* Add PR lifecycle reactions and post/update **one result comment** per run (same-repo pull requests; fork PRs are often restricted by GitHub token permissions).

Checked-out **code** is used by `mode: review` to identify the repository, branch, commit SHA, and dirty working tree state. See the action repo’s **[full guide](https://github.com/ganakailabs/cloudeval-action/blob/main/docs/github-action.md)** for details.

## Current vs planned PR capabilities

The GitHub Action path is current for CI review and PR comments. Richer GitHub-native review surfaces are still roadmap work.

| Capability                                        | Status  | Notes                                                                                                 |
| ------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| GitHub App repository sync                        | Current | Import and refresh the CloudEval project from a selected repository, branch, and source root.         |
| GitHub Actions composite action                   | Current | Run CloudEval review from a workflow runner with a scoped access key.                                 |
| PR comments                                       | Current | Post or update one review result comment for same-repo pull requests when token permissions allow it. |
| CI job failure via `.cloudeval/config.yaml` gates | Current | Fail the workflow job when configured gates are not satisfied.                                        |
| Workflow artifacts                                | Current | Upload JSON, Markdown summaries, and report artifacts from the run.                                   |
| GitHub Checks UI annotations                      | Planned | Native annotations beyond the workflow job result are not the current contract.                       |
| PR diagram diffs                                  | Planned | Architecture diff visualizations across pull-request changes are roadmap work.                        |
| Native repo scanning without setup                | Planned | Today, use the GitHub App plus action workflow for linked project review.                             |

## Prerequisites

<Steps>
  <Step title="Create a CI access key">
    In the CloudEval app, open **Developer → API & CLI access keys** and create a **GitHub Actions CI** key scoped to the target project. Review mode needs project/report capabilities, `ask:run` when AI summaries are enabled, and `github:comment` when CloudEval should post PR comments through the GitHub App identity. Older keys without `github:comment` still work, but comments fall back to `github-actions[bot]`.
  </Step>

  <Step title="Create or import the CloudEval project">
    Create or import the project from the GitHub repository through the [CloudEval GitHub App](/reference/github-repository-sync). This links the repository, branch, commit provenance, and project.
  </Step>

  <Step title="Add repository secrets">
    Add `CLOUDEVAL_ACCESS_KEY` and, for review/reports, `CLOUDEVAL_PROJECT_ID` in the consumer repository or environment.
  </Step>

  <Step title="Pin the action">
    Prefer `uses: ganakailabs/cloudeval-action@v1` or a **full commit SHA** for supply-chain control.
  </Step>

  <Step title="Require the check">
    If CloudEval should block merges, require the workflow job in a GitHub branch protection rule or ruleset.
  </Step>
</Steps>

## PR review workflow

<Steps>
  <Step title="Add the review workflow">
    ```yaml theme={null}
    name: CloudEval review
    on:
      pull_request:

    permissions:
      contents: read
      pull-requests: write
      issues: write

    jobs:
      review:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: ganakailabs/cloudeval-action@v1
            with:
              access_key: ${{ secrets.CLOUDEVAL_ACCESS_KEY }}
              project_id: ${{ secrets.CLOUDEVAL_PROJECT_ID }}
              mode: review
              post_pr_comment: true
              upload_artifacts: true
    ```

    <Frame caption="A CloudEval review workflow produces a GitHub Actions job summary, downloadable review artifacts, and a linked PR comment.">
      <img src="https://mintcdn.com/ganakailabs-db727e50/BrRYz9nGRkigfTsV/assets/images/cli/github-action-review-run.png?fit=max&auto=format&n=BrRYz9nGRkigfTsV&q=85&s=67342d68cb92577a689ce94c71b8677c" alt="GitHub Actions run page showing a completed CloudEval review job with result summary, workflow run metadata, artifact, and PR comment status" width="1496" height="760" data-path="assets/images/cli/github-action-review-run.png" />
    </Frame>
  </Step>

  <Step title="Confirm what review mode runs">
    `mode: review` runs the high-level CLI command:

    ```bash theme={null}
    cloudeval review \
      --project "$CLOUDEVAL_PROJECT_ID" \
      --repo "$GITHUB_REPOSITORY" \
      --ref "$GITHUB_REF_NAME" \
      --commit-sha "$GITHUB_SHA" \
      --format json \
      --non-interactive
    ```

    By default the command waits for GitHub sync and report refresh before writing
    `review.json` and `review.md`. Use `--no-wait` only for advanced workflows that
    want to submit sync and inspect the job separately. Review output includes an
    AI-written PR summary by default; disable it with the action input
    `ai_summary: "false"` if CI must avoid model-generated prose.

    If the runner workspace has uncommitted changes, the CLI stops with:

    ```text theme={null}
    Reviews pushed commits only. Add --ignore-dirty to review HEAD anyway.
    ```

    Set `ignore_dirty: "true"` only when your workflow intentionally generates local files before review.
  </Step>

  <Step title="Enable PR comment output">
    When `post_pr_comment: true`, the action reacts to the PR with `eyes` when
    review starts and adds a completion reaction when review finishes (`+1` for
    pass, `confused` for failure). The review details are written as one
    idempotent result comment after the run has report data.

    For projects linked through the CloudEval GitHub App, CloudEval posts that
    comment with the app installation token so the visible author is the CloudEval
    GitHub App and the comment uses the app logo. If the app comment route is not
    available or the access key does not include `github:comment`, the action falls
    back to `github-actions[bot]`.

    <Frame caption="When the project is linked to the GitHub App and the access key includes `github:comment`, the PR review appears as one CloudEval App comment with source provenance.">
      <img src="https://mintcdn.com/ganakailabs-db727e50/BrRYz9nGRkigfTsV/assets/images/cli/github-action-pr-comment.png?fit=max&auto=format&n=BrRYz9nGRkigfTsV&q=85&s=02b6dcb15d459924ffde9cd9c40743cf" alt="GitHub pull request comment by the CloudEval GitHub App showing overall review result, source provenance, AI summary, and collapsible drilldowns" width="824" height="360" data-path="assets/images/cli/github-action-pr-comment.png" />
    </Frame>

    <Frame caption="The AI summary appears directly inside the PR comment, with longer reasoning available in the expandable details section.">
      <img src="https://mintcdn.com/ganakailabs-db727e50/BrRYz9nGRkigfTsV/assets/images/cli/github-action-ai-summary.png?fit=max&auto=format&n=BrRYz9nGRkigfTsV&q=85&s=ea29646a75fc19a9ccd858a665a4fa54" alt="Expanded CloudEval PR comment showing the AI summary and AI details section" width="824" height="780" data-path="assets/images/cli/github-action-ai-summary.png" />
    </Frame>

    For an App-branded PR comment, all three pieces must be true:

    * the CloudEval project was created from or linked to the same GitHub repository
    * the CI access key is scoped to that project and includes `github:comment`
    * the workflow passes `project_id`, `post_pr_comment: true`, and has `pull-requests: write` plus `issues: write`
  </Step>

  <Step title="Inspect review drilldowns">
    <Frame caption="Review drilldowns expand in place for Well-Architected pillar scores and monthly cost breakdowns.">
      <img src="https://mintcdn.com/ganakailabs-db727e50/BrRYz9nGRkigfTsV/assets/images/cli/github-action-review-drilldowns.png?fit=max&auto=format&n=BrRYz9nGRkigfTsV&q=85&s=a0474ed29de97bc2d9cfa06b535ad489" alt="Expanded CloudEval PR comment showing Well-Architected pillar ratings and monthly cost drilldowns" width="824" height="980" data-path="assets/images/cli/github-action-review-drilldowns.png" />
    </Frame>

    <Frame caption="Validation and architecture signals stay in the same review comment so reviewers can check failures and graph context without leaving GitHub.">
      <img src="https://mintcdn.com/ganakailabs-db727e50/BrRYz9nGRkigfTsV/assets/images/cli/github-action-validation-architecture.png?fit=max&auto=format&n=BrRYz9nGRkigfTsV&q=85&s=a8d5f7bd00cb9d192244aebd066dbc15" alt="Expanded CloudEval PR comment showing validation results and architecture signals" width="824" height="280" data-path="assets/images/cli/github-action-validation-architecture.png" />
    </Frame>
  </Step>
</Steps>

## Config-driven gates

<Steps>
  <Step title="Add ci.gates">
    Add `ci.gates` to `.cloudeval/config.yaml` when the review should fail the job:

    ```yaml theme={null}
    version: 1

    # Stack selection tells CloudEval which file drives diagrams and reports.
    stacks:
      - id: primary-architecture
        name: Primary architecture
        entry: azuredeploy.json
        parameters: azuredeploy.parameters.json

    resolve:
      # Follow relative ARM templateLink files before graph/report analysis.
      linked_templates: true

    ci:
      gates:
        # block_pull_request fails the job; comment_only keeps the PR comment but does not block.
        enforcement: block_pull_request

        # Minimum Well-Architected score out of 100.
        minimum_well_architected_score: 85

        # Optional default minimum for every pillar. Per-pillar overrides below win.
        minimum_pillar_score: 80
        pillars:
          security: 90
          reliability: 85

        # Fail on high-risk architecture findings.
        fail_when_high_risk_findings_exist: true

        # Fail when policy checks or unit tests fail.
        fail_when_validation_fails: true

        # Optional monthly budget gate. Omit if cost should be reported but not gated.
        max_monthly_cost_usd: 500
    ```
  </Step>

  <Step title="Choose enforcement behavior">
    When `ci.gates` is missing, review mode returns a warning rather than failing by default. When gates exist, `enforcement: block_pull_request` fails the job on gate failures. Use `enforcement: comment_only` to publish the review without blocking merges while the team tunes thresholds. Existing `required`, `warn`, `overall_score_min`, `pillar_score_min`, `fail_on_high_risk`, `fail_on_validation_errors`, and `max_monthly_cost` keys are still accepted for compatibility.
  </Step>

  <Step title="Read the PR comment result">
    The PR comment separates the configured gate from observed posture:

    ```md theme={null}
    🟢 **Overall** : PASS
    🔴 Well-Architected Posture: 23.1/100 (CRITICAL)
    🔴 Validation: 3 unit tests failed
    🟢 Policy checks: GOOD
    🟢 Cost: 143.81 USD/mo (under 100K budget)

    #### Source

    - **CloudEval project**: [GitHub Nested E2E](https://cloudeval.ai/app/projects/...)
    - **Repository**: `owner/repo`
    - **Ref**: `feature/infra-change`
    - **Commit**: `abc123def456`
    - **Workflow run**: https://github.com/owner/repo/actions/runs/123456789
    ```

    `Overall` is the gate result from your thresholds. `CRITICAL` is the observed architecture posture. A PR can show both when thresholds are intentionally permissive, validation/high-risk failures are disabled, or the cost budget is high.
  </Step>

  <Step title="Require the workflow check">
    To block merges, configure GitHub branch protection or a repository ruleset that requires the workflow job running CloudEval review. GitHub Actions cannot prevent someone from clicking **Approve** on a pull request; the required status check is what prevents merge.
  </Step>

  <Step title="Use deterministic drilldowns">
    Review comments include deterministic drill-downs for:

    * Open in CloudEval links for the project preview, architecture report, cost report, validation details, PDF download, workflow run, and review artifacts
    * Well-Architected overall and pillar scores
    * cost threshold, estimated monthly cost, resource-cost pie chart, savings impact chart, and compact service-cost table
    * policy check and unit-test failures
    * optional AI summary, generated with `ai_summary_mode: ask` or `ai_summary_mode: agent`, split into a short summary plus collapsible details
  </Step>
</Steps>

## Prompt-based merge gate

<Steps>
  <Step title="Switch to gate mode">
    Use **`mode: gate`**, set **`gate_jq`** to a jq expression that yields one number from the CLI JSON (for example `.score`), and set **`gate_threshold`** plus optional **`gate_operator`** (`ge`, `lt`, `eq`, …).
  </Step>

  <Step title="Set PR comment permissions">
    Enable **`post_pr_comment: true`** only when the job has `pull-requests: write` plus `issues: write` and the PR is from the **same** repository (not a fork), unless you use a different token strategy. These permissions are required for PR lifecycle reactions and for the `github-actions[bot]` comment fallback. GitHub App-linked projects can post the review comment through the CloudEval App identity when the access key includes `github:comment`.
  </Step>

  <Step title="Add the gate workflow">
    ```yaml theme={null}
    permissions:
      contents: read
      pull-requests: write
      issues: write

    on:
      pull_request:

    jobs:
      cloud-eval:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: ganakailabs/cloudeval-action@v1
            with:
              access_key: ${{ secrets.CLOUDEVAL_ACCESS_KEY }}
              project_id: ${{ secrets.CLOUDEVAL_PROJECT_ID }}
              mode: gate
              ask_prompt: 'Return JSON only: {"score": <0-1>, "reason": "..."} for IaC risk in this repo.'
              gate_threshold: "0.7"
              gate_jq: ".score"
              gate_operator: ge
              post_pr_comment: true
              upload_artifacts: true
    ```
  </Step>
</Steps>

## Reports on a schedule

Set **`mode: nightly`** (or **`reports`**) with **`project_id`**, configure **`reports_type`**, and optionally **`reports_wait`** so the job waits for report jobs to finish before download.

## Why reviewers can trust the output

Every PR review should make the source and evidence path visible enough for a reviewer to check the result without guessing.

| Trust signal                | Where it appears                                                                               |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| Source project              | PR comment source section and Open in CloudEval links                                          |
| Repository, ref, and commit | PR comment source section plus workflow metadata                                               |
| Workflow run                | PR comment source section, GitHub Actions summary, and artifacts                               |
| Evidence                    | Architecture report, cost report, validation details, policy checks, and report drilldowns     |
| Next action                 | Gate result, failed checks, high-risk findings, cost threshold status, and optional AI summary |

## Reusable workflow

The action repository ships a **`workflow_call`** workflow so other repos can call one shared definition. Pass **`action_repository`** and **`action_ref`** if you fork. See **[cloudeval-reusable.yml](https://github.com/ganakailabs/cloudeval-action/blob/main/.github/workflows/cloudeval-reusable.yml)** in the action repo.

## Configuration reference

Every input and output is documented in:

* **[`action.yml` in ganakailabs/cloudeval-action](https://github.com/ganakailabs/cloudeval-action/blob/main/action.yml)** (source of truth)
* **[docs/github-action.md](https://github.com/ganakailabs/cloudeval-action/blob/main/docs/github-action.md)** (narrative guide)

## Related docs

* [Automate evaluations with the CLI](/workflows/automate-evaluations-with-the-cli) — same CloudEval service; use the action when you want a packaged GitHub-native path.
* [GitHub repository sync](/reference/github-repository-sync) — install the CloudEval GitHub App and keep project files synced from GitHub.
* [IaC project config](/reference/iac-project-config) — configure visualization source and CI gates.
* [Use the CLI](/quickstart/use-the-cli) — local install and `cloudeval login` for interactive work.