GitHub Actions integration - CloudEval AI Docs

Use the CloudEval GitHub Action when you want CloudEval review results inside GitHub Actions without hand-rolling install and auth steps.

Use the CloudEval GitHub App for repository sync into CloudEval. Use the GitHub Action for CI review, merge gates, PR comments, and report artifacts after a CloudEval project exists.

Want to see it before wiring your own repo? Inspect the passing baseline demo PR and the risk regression demo PR in the public Azure ARM review example.

Public example

Use 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	Green	A passing review with baseline thresholds while the comment still shows CRITICAL posture, validation, cost, and report links.
Risk regression	Red	A risky IaC change with blocking gate failures and high-risk posture signals.
Cost regression	Red	Five-digit monthly cost estimate, resource cost drivers, and a failing monthly budget gate.
Security hardening	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 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 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

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

Create or import the CloudEval project

Create or import the project from the GitHub repository through the CloudEval GitHub App. This links the repository, branch, commit provenance, and project.

Add repository secrets

Add CLOUDEVAL_ACCESS_KEY and, for review/reports, CLOUDEVAL_PROJECT_ID in the consumer repository or environment.

Pin the action

Prefer uses: ganakailabs/cloudeval-action@v1 or a full commit SHA for supply-chain control.

Require the check

If CloudEval should block merges, require the workflow job in a GitHub branch protection rule or ruleset.

PR review workflow

Add the review workflow

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

GitHub Actions run page showing a completed CloudEval review job with result summary, workflow run metadata, artifact, and PR comment status

Confirm what review mode runs

mode: review runs the high-level CLI command:

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:

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.

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

GitHub pull request comment by the CloudEval GitHub App showing overall review result, source provenance, AI summary, and collapsible drilldowns

Expanded CloudEval PR comment showing the AI summary and AI details section

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

Inspect review drilldowns

Expanded CloudEval PR comment showing Well-Architected pillar ratings and monthly cost drilldowns

Expanded CloudEval PR comment showing validation results and architecture signals

Config-driven gates

Add ci.gates

Add ci.gates to .cloudeval/config.yaml when the review should fail the job:

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

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.

Read the PR comment result

The PR comment separates the configured gate from observed posture:

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

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.

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

Prompt-based merge gate

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, …).

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.

Add the gate workflow

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

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 in the action repo.

Configuration reference

Every input and output is documented in:

action.yml in ganakailabs/cloudeval-action (source of truth)
docs/github-action.md (narrative guide)

Automate evaluations with the CLI — same CloudEval service; use the action when you want a packaged GitHub-native path.
GitHub repository sync — install the CloudEval GitHub App and keep project files synced from GitHub.
IaC project config — configure visualization source and CI gates.
Use the CLI — local install and cloudeval login for interactive work.

​Public example

​What it does (and does not do)

​Current vs planned PR capabilities

​Prerequisites

​PR review workflow

​Config-driven gates

​Prompt-based merge gate

​Reports on a schedule

​Why reviewers can trust the output

​Reusable workflow

​Configuration reference

​Related docs

Public example

What it does (and does not do)

Current vs planned PR capabilities

Prerequisites

PR review workflow

Config-driven gates

Prompt-based merge gate

Reports on a schedule

Why reviewers can trust the output

Reusable workflow

Configuration reference

Related docs