Documentation
ExamplesMinimal GitHub Example

Minimal GitHub Example

Simplest possible configuration to collect evidence from a single GitHub repository.

Use Case

Perfect for:

  • Getting started quickly
  • Testing evidence SDK
  • Single application repository
  • CC6.1 compliance only (2FA enforcement)

Time to first bundle: < 5 minutes

Prerequisites

  1. evidence CLI installed:

    npm install -g @evidence-oss/cli

  2. GitHub repository with admin access

  3. GitHub personal access token with scopes:

    • repo:read (or public_repo for public repos)
    • read:org

Step-by-Step Setup

1. Generate Signing Keys

evidence init --generate-keys

Output:

Generating Ed25519 key pair...
✓ Private key: ~/.evidence/keys/private.pem
✓ Public key: ~/.evidence/keys/public.pem

2. Create GitHub Personal Access Token

  1. Go to GitHub → Settings → Developer settings → Personal access tokens
  2. Click "Generate new token (classic)"
  3. Name: evidence-collection
  4. Expiration: 90 days
  5. Select scopes:
    • ✅ public_repo (for public repositories)
    • ✅ read:org
  6. Click "Generate token"
  7. Copy the token immediately (shown only once)

Token format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Set Environment Variable

export GITHUB_TOKEN=ghp_your_token_here

Make it permanent:

echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc
source ~/.zshrc

4. Create Configuration File

Create evidence.yaml in your current directory:

# evidence.yaml - Minimal GitHub configuration

framework: soc2_type1

controls:
  - CC6.1  # Logical Access Controls (2FA enforcement)

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: your-org  # Replace with your GitHub organization
    repos:
      - your-org/your-repo  # Replace with your repository

bundle:
  signing:
    private_key_path: ~/.evidence/keys/private.pem

Replace:

  • your-org → Your GitHub organization name
  • your-repo → Your repository name

Example:

sources:
  github:
    org: acme
    repos:
      - acme/backend

5. Collect Evidence

evidence collect

Expected output:

Validating configuration...
  ✓ Configuration valid
  ✓ Signing key found

Validating credentials...
  ✓ GitHub token valid
  ✓ Scopes: repo:read, read:org

Collecting from GitHub...
  → Fetching organization settings
  ✓ Organization: acme
  ✓ 2FA enforcement: enabled

Creating bundle...
  ✓ Manifest generated
  ✓ Checksums computed (3 files)
  ✓ Signature created

✓ Collection complete

Bundle created: evidence-bundles/evidence-bundle-20260110-093045.tar.gz
Size: 8.2 KB
Artifacts: 1
Controls: CC6.1

6. Verify Bundle

evidence verify evidence-bundles/evidence-bundle-*.tar.gz

Expected output:

Verifying bundle...
  ✓ Checksums valid (3/3 files)
  ✓ Signature valid

Bundle is authentic and unmodified.

Bundle Details:
  Framework: soc2_type1
  Controls: CC6.1
  Sources: github
  Artifacts: 1
  Created: 2026-01-10T09:30:45Z

What Gets Collected

Single artifact:

File: sources/github/org_settings.json

Content:

{
  "login": "acme",
  "id": 12345678,
  "two_factor_requirement_enabled": true,
  "default_repository_permission": "read",
  "members_can_create_repositories": false
}

Control mapping:

  • CC6.1: two_factor_requirement_enabled: true ✅

Complete File Structure

your-project/
├── evidence.yaml                  # Configuration (created in step 4)
├── evidence-bundles/              # Output directory (auto-created)
│   └── evidence-bundle-20260110-093045.tar.gz
└── ~/.evidence/keys/              # Signing keys (created in step 1)
    ├── private.pem
    └── public.pem

Next Steps

Add More Controls

controls:
  - CC6.1  # Logical Access Controls
  - CC6.6  # Access Removal/Modification
  - CC7.2  # Change Management

Requires:

  • CODEOWNERS file in repository (CC6.6)
  • Branch protection configured (CC7.2)

Add More Repositories

sources:
  github:
    org: acme
    repos:
      - acme/backend
      - acme/frontend  # Add more repos
      - acme/api

Or use wildcard:

repos: '*'  # All repos in organization

Automate Collection

Set up GitHub Action to collect monthly:

# .github/workflows/evidence-collection.yml
name: Evidence Collection
on:
  schedule:
    - cron: '0 0 1 * *'  # First day of each month

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install evidence CLI
        run: npm install -g @evidence-oss/cli

      - name: Setup signing key
        run: |
          mkdir -p ~/.evidence/keys
          echo '${{ secrets.EVIDENCE_SIGNING_KEY }}' > ~/.evidence/keys/private.pem
          chmod 600 ~/.evidence/keys/private.pem

      - name: Collect evidence
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: evidence collect

      - name: Upload bundle
        uses: actions/upload-artifact@v4
        with:
          name: evidence-bundle
          path: evidence-bundles/*.tar.gz

See: GitHub Action Workflow Example

Troubleshooting

Token Authentication Failed

Error:

✗ GitHub token invalid
Error: Bad credentials (HTTP 401)

Solution:

# Verify token is set
echo $GITHUB_TOKEN

# Test token manually
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user

Organization Not Found

Error:

✗ Organization 'your-org' not found

Solution:

  • Verify organization name spelling
  • Check token has access to organization
  • If SSO enabled, authorize token for organization

2FA Not Enforced

Warning:

⚠ CC6.1: Failed
  two_factor_requirement_enabled: false

Solution:

  1. Go to GitHub Organization → Settings → Authentication security
  2. Enable "Require two-factor authentication for everyone"
  3. Members have 7 days to enable 2FA
  4. Re-run collection after enforcement active

Full Example

Complete working example:

# evidence.yaml
framework: soc2_type1

controls:
  - CC6.1

sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos:
      - acme/backend

bundle:
  signing:
    private_key_path: ~/.evidence/keys/private.pem
  output_path: ./evidence-bundles

Environment:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Commands:

# Generate keys
evidence init --generate-keys

# Collect
evidence collect

# Verify
evidence verify evidence-bundles/evidence-bundle-*.tar.gz

# Inspect
tar -xzf evidence-bundles/evidence-bundle-*.tar.gz -C /tmp/inspect
cat /tmp/inspect/manifest.json | jq

See Also

Troubleshooting

Common issues, solutions, and debugging techniques for evidence collection.

Multi-Source Example

Production configuration collecting evidence from GitHub, AWS, and Google Workspace.

On this page

Use CasePrerequisitesStep-by-Step Setup1. Generate Signing Keys2. Create GitHub Personal Access Token3. Set Environment Variable4. Create Configuration File5. Collect Evidence6. Verify BundleWhat Gets CollectedComplete File StructureNext StepsAdd More ControlsAdd More RepositoriesAutomate CollectionTroubleshootingToken Authentication FailedOrganization Not Found2FA Not EnforcedFull ExampleSee Also