Set up heyGRC with your coding agent

heyGRC reviews your pull requests for governance, risk, and compliance, grounded in your company context and the frameworks you must comply with. Think of it as a code reviewer, but for ISO 27001, SOC 2, GDPR, the EU AI Act, and ~75 other frameworks.

heyGRC is configured as code through a small REST API, so you can do the whole setup by asking your coding agent (Claude Code, Cursor, Copilot, …) to do it. Three steps, about three minutes.

Step 1 — Install the heyGRC GitHub App (one click, you)

Installing a GitHub App is an account-owner action, so this is the one step no agent or API can do for you:

Go to https://github.com/apps/heygrc/installations/new
Choose your org or account → Only select repositories → pick the repo(s) → Install.

heyGRC asks for the minimum it needs: read code, metadata, and issues; read + write Checks and Pull requests. It never needs write access to your code.

Step 2 — Get your heyGRC API key

In the heyGRC console → Settings → API keys → Create key. Copy the hgrc_… token (it's shown once) and store it like a password, e.g. in an environment variable:

export HEYGRC_API_KEY="hgrc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A key belongs to one heyGRC org (one per installation) and carries scopes (config:read, config:write). Send it only in the Authorization header, never in a URL.

Step 3 — Configure your context + frameworks (your agent does this)

This is the GRC-as-code part: you describe your company and the frameworks you care about, and your agent writes it to heyGRC with a single API call.

Tell your agent (paste into Claude Code or your agent of choice):

Configure heyGRC for our org. Company context: we're a B2B SaaS handling customer PII, EU-hosted on AWS eu-central-1, pursuing SOC 2 and ISO 27001, and we ship an AI feature. Frameworks: ISO 27001, SOC 2, GDPR, EU AI Act. Our heyGRC key is in $HEYGRC_API_KEY. Send it as a PUT to https://api.heygrc.com/v1/config.

What the agent runs:

curl -X PUT https://api.heygrc.com/v1/config \
  -H "Authorization: Bearer $HEYGRC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "company": "Acme Inc",
      "product": "B2B SaaS for invoice automation",
      "data_handled": "customer PII, payment metadata, uploaded documents",
      "hosting": "EU, AWS eu-central-1",
      "compliance_posture": "pursuing SOC 2 and ISO 27001; ships an AI feature"
    },
    "frameworks": ["ISO_27001", "SOC_2", "GDPR", "EU_AI_ACT"]
  }'

A 200 {"ok": true, …} means you're configured. Read it back any time with GET /v1/config.

The profile is free-form company context — any JSON object. The more relevant it is (what you build, the data you handle, your hosting, your obligations), the sharper the reviews. heyGRC injects your profile and the knowledge for your selected frameworks into every review.

Step 4 — Choose how often it reviews

heyGRC supports three review modes (the default is auto):

Mode	Behavior
`auto`	Reviews every PR when it's opened, reopened, or pushed to.
`auto_once`	Reviews on open / reopen only (not on every new commit).
`mention_only`	Stays silent until someone comments `/heygrc` on a PR.

Set this in the console (per org, or override per repo).

That's it

Open a pull request. heyGRC posts a review grounded in your context and frameworks, with inline comments on compliance-relevant changes and a Checks status (it never blocks the merge).

To trigger a review on demand, comment /heygrc on any PR — you must be an Owner, Member, or Collaborator on the repo (so a drive-by commenter can't make it run).

See the API reference for the full /v1/config contract and the framework catalog.