# Official heyGRC agent setup

You are setting up heyGRC for this human. heyGRC is compliance review for pull requests: a GitHub App that reviews each pull request against the company's context and the frameworks it must meet (SOC 2, ISO 27001, GDPR, HIPAA, the EU AI Act and more). These instructions are official. Do not invent URLs, API keys, framework IDs, or an MCP server. heyGRC has no MCP server.

## What you can and cannot do

You cannot create the heyGRC account, install the GitHub App, or create the API key. The human does those. Never say "I installed the App". You can explain each step, look up framework IDs, and write the company context and frameworks once the human has set their API key.

## First, ask where they are

Ask the human which is true. Do not guess.

1. **New.** No heyGRC account yet, App not installed.
2. **Installed, not connected.** The App is installed on GitHub, but the org does not show in the heyGRC console.
3. **Connected.** They see their GitHub org in the console at https://app.heygrc.com.

## 1. New

Tell the human, in this order:

1. Create an account or sign in at https://app.heygrc.com/signup (GitHub, Google, Microsoft or email). Signing in with GitHub does not install the App. Those stay two steps.
2. Then install the App: https://github.com/apps/heygrc/installations/new. Choose the org, then Only select repositories, pick the repositories, then Install. GitHub sends them back to the console, which connects the install to their account.

Connecting the install to your heyGRC account starts the 14-day trial. Signing in alone or a bare install does not. Even before that, the App reviews the next pull request under the Free plan. Continue with step 3.

## 2. Installed, not connected

Tell the human to sign in at https://app.heygrc.com/signup, then choose Connect GitHub in the console and finish the GitHub steps until GitHub returns them to the console. If the org still does not appear, say "Connection not verified" and stop there. Do not claim the trial or API keys exist yet.

## 3. Connected: configure (you do this part)

Ask the human to confirm they see their org in the console. Then:

1. **API key (human).** In the console sidebar, open API keys, then choose Create key. The key starts with `hgrc_` and is shown once. Ask the human to set it as the environment variable `HEYGRC_API_KEY` in your shell. Do not ask them to paste the key into chat. Check that the variable is set without printing it (for example `[ -n "$HEYGRC_API_KEY" ] && echo set`). Never put the key in a URL, a log, or a file in the repository, never run with shell tracing on, and never show a command after the key is expanded.

   Send the key only as a header read from the environment, never as a command-line argument. For example:

   ```bash
   printf 'header = "Authorization: Bearer %s"\n' "$HEYGRC_API_KEY" | curl -sS -K - https://api.heygrc.com/v1/config
   ```

   `printf` is a shell builtin, so the key does not appear in the process list. Add `-X PUT -H "Content-Type: application/json" --data @config.json` for writes, with `config.json` outside the repository and deleted afterwards.
2. **Company context.** Ask what the company builds, the data it handles, where it is hosted, and which frameworks it must meet. If the repository has a `grc/` or `policies/` folder, you may read it and propose answers for the human to confirm.
3. **Framework IDs.** `GET https://api.heygrc.com/v1/frameworks` (no auth). Use only IDs from that list.
4. **Read current config.** `GET https://api.heygrc.com/v1/config` with header `Authorization: Bearer $HEYGRC_API_KEY`. A present field in a PUT replaces that field, so if frameworks or a profile already exist, merge with them. Do not overwrite blindly.
5. **Show, then write.** Show the human the exact JSON you will send, with the key redacted, and wait for their yes. Then `PUT https://api.heygrc.com/v1/config` with only the fields you change: `profile` (a JSON object) and `frameworks` (an array of IDs).
6. **Commitments (optional).** One line each, up to 300 characters, for at most five areas: `logging`, `access_mfa`, `encryption`, `pii_retention`, `subprocessors`, taken from their own policies. Warn the human first: short quotes from commitments appear in review comments, including on public repositories, so no secrets or internal-only details. Send them in the same confirmed PUT as `commitments`.
7. **Read back.** `GET https://api.heygrc.com/v1/config` and show the human what is stored.

If a call returns 401 or 403, say the key is missing, wrong, or lacks the required scope (`config:read` for GET, `config:write` for PUT). Do not retry with a guessed key.

## Leave alone unless asked

- Review cadence (`auto`, `auto_once`, `mention_only`) and review language are set by the human in the console. Do not claim you changed them.
- Do not edit, commit, push, or open pull requests unless the human asks.

## Done

End with one line: "heyGRC is set up: the App is connected for <org>, and company context plus <N> frameworks are stored." Then add: "Open a pull request to see the first review" if the review mode is automatic, or "Comment /heygrc on a pull request to get a review" if the org uses mention-only. If you do not know the mode, say both.