Linked documents

heyGRC is never the primary place you keep a DPA or policy. You keep that document where you already govern it. A linked document is a snapshot heyGRC reads from that source, so a pull request that conflicts with it can quote your own words instead of asking whether the policy exists.

Linked documents are optional. An organization with none gets exactly today's review.

The card is on the Context page at app.heygrc.com. See Where your policies live for the page itself.

Your policy set

• Link up to 20 documents per organization, in any mix: a DPA, a privacy policy, secure development, AI, operations or any other policy you keep.
• Each document has its own name. There is no document type to pick.
  • From Google Drive: the Drive file name.
  • From a link: the name you type, or the link's host and path if you leave it empty.
• Owners and admins can rename a document from its row. The card shows how many you have linked ("Documents linked: 3 of 20").
• Replace a document or Read again from its row. Linking a new file or link adds a document; it never replaces another one. Linking the same file or link again re-reads that document instead of adding a copy.
• At 20, remove one to link another.

Team conventions that are not company policy (for example "say whether you regenerated the API client") belong in .heygrc.md instead. See Writing team rules heyGRC can check.

In the console

Open Context and use the Linked documents card.

Google Drive

Connect the Google account that holds your policies, then choose a file in Google's file picker, or open it from Google Drive with Open with, then heyGRC. The file stays private in your Drive. heyGRC can read only the files you pick, and never changes them.

heyGRC reads these Drive files:

• Google Docs
• Plain text, Markdown and HTML files (UTF-8, UTF-16 or Windows-1252 encoding)
• Word files (.docx)

Old Word files (.doc) are not read: save them as .docx first. Drive files are limited to 8 MB.

Quotes from a private Drive document appear only on private repositories.

Paste a link

1. Click Link a document.
2. Paste a public HTTPS URL that returns HTML, Markdown, or plain text. A Google Drive or Docs share link works when anyone with the link can view it.
3. Optionally type a name.
4. Read the warning: this document is used across the organization's connected repositories, and short quotes may appear in pull request comments, including public repositories.
5. Click Use this document. Pasting a URL does nothing until this click.

If the snapshot validates, reviews start quoting it. There is no extra confirm step.

PDF and Word (.docx) files are not read through a URL. Link Word files from Google Drive instead. Private-file URLs are rejected. File upload is retired.

Re-reads

heyGRC checks linked documents for changes daily. You can also read a document again from its row at any time. A failed re-read keeps the last good snapshot.

Card states

• Reading. heyGRC is fetching and compiling. If you already had a snapshot in use, reviews keep using it while the update is read.
• In use. Source and last-read date.
• Could not read. Public-safe reason. Reviews stay as they were.
• Not in use yet. The compiler flagged gaps, so this version was not turned on. The previous in-use snapshot, if any, stays. If the card says the check has changed, click Read again.

Remove stops new reviews from using that document. Comments already on GitHub, including quotes, stay exactly as they are.

How a review uses it

Frameworks still run. Reviews draw on every linked document. A linked document only speaks when the diff touches something it is about (a named processor, a retention rule, a region, an engineering rule).

Engineering policies (secure development, AI, operations and the like) have their own reader that keeps more of their binding rules, so reviews can apply them. Documents read before 15 October 2026 use it after they change or you click Read again.

• A CSS-only or test-only PR: linked documents stay idle. That review is today's review.
• A PR that conflicts with a document: the finding quotes a short verbatim span of your source (at most 120 characters), not a paraphrase and not the contract body.
• A vendor your documents never name is unknown, not banned. Ordinary framework findings may still fire.

Names on GitHub

• Private repositories: review comments may name the document they quote.
• Public repositories: comments never name the document.

Short quotes of your document on your pull request are the point. Do not put secrets in a document you link.

As code (any agent or harness)

Agents attach a live HTTPS URL. Writes need a key with config:write. Reads need config:read. Google Drive is not an API source.

GET /v1/review-packs returns the primary document at the top level, as before, plus a documents array with one entry per linked document. Each entry has pack_id, kind, label (the name), a draft and confirmed summary (status, clause count, content hash, source URL, confirmed_at) and reread (due_at, attempted_at, last_outcome, last_verified_unchanged_at). It never returns the full extracted text of your document: the top-level snapshot lists the compiled rules with their short verified quotes, and documents entries carry no rule text at all.

Submit. A submit adds a new document unless it carries a pack_id (that document is replaced; take it from documents) or the same URL is already linked (that document is replaced, which is also how you refresh it). kind is optional and legacy: it no longer limits anything. If you pass a kind other than other and exactly one document has it, that document is replaced. use defaults to true: the same authorization as Use this document. When compile validates, the worker activates the snapshot.

curl -X POST https://api.heygrc.com/v1/review-packs \
  -H "Authorization: Bearer $HEYGRC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Secure development policy",
    "source": { "type": "url", "url": "https://example.com/secure-development.md" },
    "use": true
  }'

source.type must be url. HTTP URLs, credentials in the URL, and private or local hosts are rejected. A Google Drive or Docs share link is a URL. Set "use": false only if you want a draft that is not put in use (console never does this).

Poll GET /v1/review-packs until confirmed is present, or the draft compiler_status is failed or needs_review. needs_review never activates.

DELETE /v1/review-packs removes one linked document: pass ?pack_id=<uuid> (from documents). ?kind=privacy still works when exactly one document has that kind. ?all=true removes every linked document of the organization. A DELETE with none of these returns 400 kind_required and deletes nothing. Past reviews keep citation text they already posted; new reviews stop using the removed document.

Errors:

• 400 invalid_kind: unknown kind on submit or delete.
• 400 kind_required: bare DELETE.
• 404 pack_not_found: DELETE names no linked document with that id or kind in your organization, or a submit passes an unknown pack_id.
• 409 ambiguous_kind: DELETE ?kind= when more than one document has that kind. Delete by pack_id.
• 409 pack_limit_reached: the organization already has 20 linked documents.
• 429 compile_cap_exceeded: the daily read limit is spent.

A natural agent prompt: "Our secure development policy is at this HTTPS URL (a Google Docs share link is fine if anyone with the link can view it). POST it to heyGRC /v1/review-packs with a short label and use true. Poll GET until confirmed is set, or until the draft failed. Do not call /confirm. Do not upload a file. Do not put the document body on GitHub."

Limits

• 20 linked documents per organization, any mix.
• 25 reads per organization per UTC day (429 compile_cap_exceeded). Scheduled daily re-reads do not count; Read again and API re-posts do.
• Name: 1 to 80 characters, no control characters.
• HTTPS URL only, 12 to 2048 characters, no credentials.
• Google Drive files: 8 MB.
• Quotes on GitHub: verbatim source spans, at most 120 characters, at most 3 quotes or 360 characters per review.