Skip to main content

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 repository sync keeps GitHub as the source of truth for an Infrastructure as code project. CloudEval imports the selected branch and source root, reads .cloudeval/config.yaml when present, resolves linked templates, and refreshes diagrams and reports.

​
Why it matters

Use this path when your source has multiple files, linked ARM templates, or a repository layout you want to keep in GitHub. Source files are read-only in CloudEval while the project is linked to GitHub.

​
Quick start

  1. Open Projects.
  2. Select New or Quick.
  3. Choose Infrastructure as code.
  4. Choose GitHub repository.
  5. Install the CloudEval GitHub App if prompted.
  6. Pick the GitHub account or organization, repository, branch, and optional source root.
  7. Create the project.
CloudEval imports files, resolves the stack, and starts diagram/report generation in the background. 
.cloudeval/
  config.yaml
azuredeploy.json
azuredeploy.parameters.json
nested/
  network.json
  storage.json
README.md

# .cloudeval/config.yaml
version: 1
stacks:
  - id: main
    entry: azuredeploy.json
    parameters: azuredeploy.parameters.json
resolve:
  linked_templates: true
analysis:
  auto_resolve_on_import: true
  auto_refresh_on_resolve: true
The entry file is the visualization source. Relative ARM templateLink files are resolved from the same workspace root.

​
User and project mapping

GitHub does not decide which CloudEval user owns a project. CloudEval maps the GitHub App installation to the signed-in CloudEval user who starts the install flow. If an organization admin installs the app, the project still belongs to the CloudEval user who completed the flow. For team use, share the CloudEval project with teammates after creation.

​
What GitHub data CloudEval stores

CloudEval stores provenance on the project: 
{
  "type": "github",
  "installation_id": 123456,
  "repo_full_name": "org/repo",
  "ref": "main",
  "commit_sha": "abc123",
  "source_root": "infra",
  "display_label": "org/repo main"
}
CloudEval does not store long-lived GitHub access tokens. It stores the installation id and mints short-lived installation tokens server-side when it needs to list repositories, fetch files, or process a sync.

​
Sync behavior

ActionWhat happens
Project creationImports selected files, resolves .cloudeval/config.yaml, starts diagram/report jobs
Push to selected branchGitHub sends a signed webhook; CloudEval imports the new commit and refreshes analysis
Sync from GitHubManually runs the same import/resolve/refresh path
GitHub App removedCloudEval marks the installation unavailable; reconnect GitHub before syncing again
Public repositories can be imported through a GitHub URL for a one-time single-template flow. Use the GitHub App flow when you want ongoing sync, commit provenance, branch selection, and push webhooks.

​
Files CloudEval imports

CloudEval preserves repository-relative paths under the selected source root. For example, source_root: infra maps infra/azuredeploy.json to azuredeploy.json in the CloudEval workspace. CloudEval skips unsafe or noisy paths:
  • .git/**
  • .github/**
  • node_modules/**
  • .terraform/**
  • *.tfstate and *.tfstate.*
  • .env and .env.*
  • CloudEval-generated .cloudeval/bundles/**, .cloudeval/connections/**, .cloudeval/template-cache/**, .cloudeval/snapshots/**, and .cloudeval/ps-rule.yaml

​
GitHub App permissions

For V1 repository sync, the GitHub App needs only read-oriented repository access:
Permission or eventWhy
Metadata readIdentify installed repositories and account/org metadata
Contents readRead source files from the selected branch/source root
Push eventRefresh linked projects when the selected branch changes
Pull request permissions are not required for V1 sync. They are only needed for later PR comments, checks, or GitHub Action workflows.

​
GitHub Actions

The CloudEval GitHub Action is optional. It is useful after a project exists when you want CI gates, report runs, or PR comments. It is not required for repository sync.

​
Troubleshooting

SymptomFix
Repository does not appearReinstall or update the GitHub App and include that repository in the selected access list
Branch list is emptyConfirm the GitHub App still has contents read access to the repo
Sync says GitHub is disconnectedThe app was removed or suspended; reconnect from the GitHub repository source picker
Diagram/report does not include linked filesAdd or fix .cloudeval/config.yaml and set stacks[].entry to the parent template
Source file cannot be editedThis is expected for GitHub-linked projects. Edit in GitHub, then sync again
Last modified on May 25, 2026