Heva Sentinel GitHub Action

Shared GitHub automation for Heva repositories.

This repo is now the central home for CRG indexing. The old Claude commit-review and direct Google Chat posting flow is deprecated; heva-google-chat-bot owns chat orchestration, Jira/GitHub decisions, and PR worker handoff.

This repository is active infrastructure. Do not archive it as a deprecation mechanism; disable or fix a specific unsafe workflow path instead.

What This Does

CRG means code-review-graph: a branch-level AST/code graph generated from a checked-out repository. The bot and coding worker use the graph as evidence before broad source search.

On every configured branch push, product repos call the reusable workflow here:

product repo push
-> checkout exact repo + branch + commit
-> install latest code-review-graph from Python/PyPI
-> run code-review-graph build
-> produce graph.db + manifest.json + status.txt
-> upload GitHub artifact and optional GCS artifact
-> heva-bot/Claude worker can fetch by repo + branch + sha

The same reusable workflow also supports manual backfill from this repo. In backfill mode, metadata is written for the target repo/branch/commit, not for this sentinel repo.

CRG Version

Default is latest:

python3 -m pip install --upgrade code-review-graph

You can pin if needed:

with:
  crg-version: "2.3.2"

Or use a direct pip install spec:

with:
  crg-version: "git+https://github.com/tirth8205/code-review-graph.git@<commit-sha>"

Do not copy the CRG source code into this repo. This repo installs CRG and runs it against each target repo.

Platform Installs

code-review-graph install --platform ... configures MCP/instructions/hooks for coding tools such as Claude Code, Codex, Cursor, Gemini CLI, Kiro, or Copilot.

Normal CI indexing does not need platform install. It only needs:

code-review-graph build --repo "$GITHUB_WORKSPACE" --data-dir "$CRG_DATA_DIR"

If a worker image or special repo does need CRG tool config, pass:

with:
  configure-platforms: "claude-code,codex"

That runs:

code-review-graph install --platform claude-code --yes
code-review-graph install --platform codex --yes

Add To A Product Repo

Copy examples/crg-caller.yml into the product repo as:

.github/workflows/update-crg.yml

Default branch set:

on:
  push:
    branches:
      - dev
      - stg
      - pre-prd
      - stage
      - main

Not every repo has every branch. Missing branches are fine; they simply never trigger. For regeneration on push, the workflow file must exist on the branch receiving the push, so roll this workflow into each maintained branch over time.

Initial Backfill

Do not wait for the next code push. After merging this repo, run initial CRG backfill for each routeable repo/branch.

For one repo/branch, use the manual reusable index workflow in this repo:

Actions -> Heva CRG Index -> Run workflow

Inputs:

target-repository = Heva-Co/heva-provider-frontend
target-ref        = main | dev | stg | pre-prd | stage
crg-version       = latest

For the known routeable repo/branch set, use:

Actions -> Backfill Routeable CRG -> Run workflow

That matrix covers the primary routeable product repos from the bot config, including dev, stg, pre-prd, stage, and main where applicable. The reusable workflow checks branch existence first, so a missing branch is skipped cleanly instead of blocking the rest of the backfill.

If checking out another private repo from this repo needs broader access, provide CRG_CHECKOUT_TOKEN as an org/repo secret. The installed heva-code-bot GitHub App can also be used later to mint scoped installation tokens for this same purpose.

The workflow fails if the target repository itself is not accessible. It only skips when the repository is accessible and the requested branch is missing.

Branch Policy

Use the bot repo’s config/repos.json as source of truth for routeable repos and environment branches.

Known branch patterns:

Environment	Default branch
dev	dev
staging	stg
preprod	pre-prd
prod	main
provider mobile staging	stage

Wallet repos do not currently have a preprod branch/environment. Admin is not deployed. The index workflow should skip missing branches instead of treating them as failures during org-wide backfill.

Artifacts

Each run produces:

graph.db
manifest.json
status.txt
crg-<repo>-<branch>-<sha>.tar.gz

manifest.json includes:

{
  "repository": "Heva-Co/heva-provider-frontend",
  "branch": "main",
  "commit_sha": "...",
  "crg_version": "...",
  "graph": {
    "path": "graph.db",
    "stats": {
      "nodes": 123,
      "edges": 456
    }
  }
}

GitHub artifacts are useful for debugging and short retention. Durable bot lookup should use GCS or a later CRG service/MCP store keyed by:

organization/repository/branch/commit_sha

GCS Upload

If gcs-bucket is set, the action uploads:

gs://<bucket>/<prefix>/objects/<owner>/<repo>/<branch>/<sha>/crg.tar.gz
gs://<bucket>/<prefix>/latest/<owner>/<repo>/<branch>/latest.json

The sha-keyed tarball is the durable artifact. The latest.json pointer is rewritten on every successful indexing so the bot can resolve the current graph from a known path without listing.

The caller workflow authenticates to GCP via Workload Identity Federation. Required org-level GitHub variables (not secrets — these are public identifiers, the security boundary is the GCP-side WIF binding):

GCP_WIF_PROVIDER     # full WIF provider resource path (terraform output crg_wif_provider)
GCP_PUBLISHER_SA     # crg-publisher SA email      (terraform output crg_publisher_sa)
GCP_BUCKET           # heva-crg-<project_number>   (terraform output crg_bucket)

These match the names used by heva-bot/.github/workflows/crg-sentinel.yaml and heva-bot/templates/.github/workflows/crg-publish.yaml so a single org-var configuration unblocks every CRG-touching workflow.

If gcs-bucket is provided without GCP_WIF_PROVIDER / GCP_PUBLISHER_SA, the workflow fails early with a clear auth error. Without gcs-bucket, artifacts are uploaded to GitHub Actions only.

How Heva Bot Uses This

heva-google-chat-bot should not guess from all source code first. Its order should be:

chat/screenshot evidence
-> repo/env/branch routing from config/repos.json
-> Jira/GitHub already-fixed search
-> CRG freshness lookup for candidate repo + branch + sha
-> CRG evidence pack to Claude/worker
-> source search fallback if CRG is missing or stale

For "is this fixed?", the bot should check Jira/GitHub/CRG before raising any PR. For "fix this", the worker should receive the CRG artifact for the target branch if fresh; otherwise it should regenerate or fall back to direct source inspection and record that CRG was stale/missing.