GitHub Evidence Fetcher

Flow's GitHub Evidence Fetcher helps teams collect live technical evidence for selected compliance controls without leaving the platform. From a compliance item's Evidence tab, you can fetch GitHub artifacts, review what was found, add an auditor-friendly narrative, and save the result as evidence.

Overview

The GitHub Evidence Fetcher is designed for controls where GitHub configuration is part of the proof. It currently supports selected SOC 2 control families and fetches artifacts directly from the GitHub REST API using a GitHub Personal Access Token (PAT).

What this feature provides:

• In-product evidence collection - Fetch GitHub evidence from inside a compliance item
• Control-aware artifact selection - Only fetches artifacts mapped to the current control family
• Confidence scoring - Scores the completeness of the returned evidence as LOW, MEDIUM, or HIGH
• Narrative capture - Add an explanation of what the artifacts demonstrate before saving
• Evidence traceability - Saves the result into Flow's evidence library linked to the compliance item

Supported Controls

The fetcher currently appears only for compliance requirements whose controlFamily is mapped to GitHub evidence collection.

Control family	Typical use	Artifacts fetched
CC6	Logical access and change governance	Branch protection, CODEOWNERS, organization teams
CC7	Change monitoring and detection	Repository webhooks
CC8	Change management safeguards	Branch protection

If a compliance item does not belong to one of these control families, the GitHub fetcher is not shown.

Requirements

Before fetching evidence, you need:

• A GitHub organization name
• A repository name inside that organization
• A GitHub Personal Access Token with read:org and repo scopes

The token is used only for the live fetch. The UI does not persist it after use, and the backend strips it out of request logging before writing diagnostic logs.

How To Use It

1. Open Compliance and select a compliance item that maps to CC6, CC7, or CC8.
2. Open the Evidence tab in the compliance item detail dialog.
3. In the Fetch from GitHub panel, enter:
   • Your GitHub organization name
   • Your repository name
   • A PAT with read:org and repo
4. Click Fetch artifacts.
5. Review the returned artifacts and confidence level.
6. Write an evidence narrative describing what the artifacts prove for the control.
7. Click Save as evidence.

After saving, the evidence item is linked to the current compliance item and appears alongside manually uploaded evidence.

What Flow Fetches

Flow chooses GitHub endpoints based on the current control family:

For CC6

• Branch protection from the repository's default branch
• The repository CODEOWNERS file
• Organization teams from the GitHub org

For CC7

• Repository webhooks

For CC8

• Branch protection from the repository's default branch

Flow automatically resolves the repository's default branch before fetching branch protection settings.

Confidence Scoring

Confidence is based on how many expected artifacts were found for the control family:

Score	Coverage
LOW	0-33% of expected artifacts found
MEDIUM	34-66% of expected artifacts found
HIGH	67-100% of expected artifacts found

Examples:

• CC6 with 1 of 3 artifacts found results in LOW
• CC6 with 2 of 3 artifacts found results in MEDIUM
• CC6 with 3 of 3 artifacts found results in HIGH
• CC7 or CC8 with the single expected artifact found results in HIGH

When the evidence is saved:

• HIGH and MEDIUM confidence are marked as reliable evidence
• LOW confidence is still saved, but Flow adds a note recommending manual verification

Missing Artifacts And Errors

Not every missing artifact is treated as a hard failure.

• If an optional artifact such as CODEOWNERS is not present, Flow marks it as not found and lowers confidence.
• If the PAT is invalid during the initial repository lookup, Flow returns a token error.
• If the token lacks organization access during the initial repository lookup, Flow returns a scope/access error.
• If GitHub rate limits the initial repository lookup, Flow surfaces a retry message.
• If the repository is private and the token lacks repo, Flow reports the repository as inaccessible.
• For individual artifact fetches, non-success GitHub responses are currently treated as missing artifacts rather than hard failures, which lowers confidence instead of blocking the fetch.

This makes the fetcher useful even when evidence is only partially available.

Best Practices

• Use a PAT created specifically for audit and evidence collection workflows, with only the scopes the current fetcher requires.
• Review artifacts before saving and explain why they satisfy the control.
• Treat LOW confidence results as supporting evidence, not final proof.
• Re-fetch after major GitHub policy changes such as new branch protection rules or webhook updates.
• Pair fetched artifacts with policies, procedures, and review records for stronger audit packages.

Related Docs

• Compliance Management
• Data Export