Evidence SDK GitHub Action

Automate SOC 2 compliance evidence collection in your CI/CD pipeline.

Quick Start

Add this workflow to .github/workflows/evidence.yml:

name: Collect Evidence
on:
  schedule:
    - cron: '0 0 * * 0' # Weekly on Sunday
  workflow_dispatch:

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

      - uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence.yaml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}
          EVIDENCE_API_KEY: ${{ secrets.EVIDENCE_API_KEY }}

Use Cases

1. Scheduled Evidence Collection

Collect evidence automatically on a schedule (weekly, monthly, etc.):

name: Collect SOC 2 Evidence
on:
  schedule:
    - cron: '0 0 * * 0' # Weekly on Sunday at midnight UTC
jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence.yaml
          output-path: ./evidence-bundles
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}

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

2. Verify Bundle on Pull Request

Verify evidence bundle integrity when changes are made:

name: Verify Evidence Bundle
on:
  pull_request:
    paths:
      - 'evidence-bundle.tar.gz'
      - 'evidence.yaml'

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

      - uses: evidence-sdk/action@v1
        with:
          command: verify
          bundle-path: ./evidence-bundle.tar.gz

3. Collect and Auto-Upload

Collect evidence and automatically upload to Evidence platform:

name: Collect and Upload Evidence
on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 1 * *' # Monthly on 1st

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

      - uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence.yaml
          upload: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}
          EVIDENCE_API_KEY: ${{ secrets.EVIDENCE_API_KEY }}

4. Manual Upload of Existing Bundle

Upload a previously generated bundle:

name: Upload Evidence Bundle
on:
  workflow_dispatch:

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

      - uses: evidence-sdk/action@v1
        with:
          command: upload
          bundle-path: ./evidence-bundle.tar.gz
        env:
          EVIDENCE_API_KEY: ${{ secrets.EVIDENCE_API_KEY }}

Inputs

| Input | Description | Required | Default | | ------------- | ---------------------------------------------- | -------- | -------------------- | | command | Command to run (collect, verify, upload) | Yes | - | | config-path | Path to evidence.yaml config file | No | ./evidence.yaml | | output-path | Output directory for bundles (collect command) | No | ./evidence-bundles | | bundle-path | Path to bundle file (verify/upload commands) | No | - | | upload | Auto-upload after collection (true/false) | No | false | | cli-version | Evidence CLI version to use | No | latest |

Outputs

| Output | Description | | ------------- | ------------------------------------------ | | bundle-path | Path to generated bundle (collect command) | | bundle-id | Bundle ID from manifest | | upload-url | URL of uploaded bundle (if upload=true) |

Environment Variables

Configure these as GitHub secrets:

Required for Collection

• GITHUB_TOKEN - GitHub access token with repo:read and org:read scopes
• AWS_ACCESS_KEY_ID - AWS access key (if collecting AWS evidence)
• AWS_SECRET_ACCESS_KEY - AWS secret key (if collecting AWS evidence)
• GOOGLE_CREDENTIALS - Google Workspace service account JSON (if collecting Google Workspace evidence)
• EVIDENCE_SIGNING_KEY - Ed25519 private key for bundle signing

Required for Upload

• EVIDENCE_API_KEY - API key for Evidence platform upload

Optional

• EVIDENCE_API_URL - Custom API URL (defaults to Evidence platform)

Configuration

Create an evidence.yaml file in your repository:

framework: soc2_type1

controls:
  - CC6.1
  - CC6.6
  - CC7.2

sources:
  github:
    mode: 'token'
    token_env: 'GITHUB_TOKEN'
    org: 'myorg'
    repos:
      - 'myorg/backend'
      - 'myorg/frontend'

  aws:
    mode: 'env'
    region: 'us-east-1'
    log_groups:
      - '/aws/lambda/critical-function'

  google_workspace:
    mode: 'service_account'
    credentials_env: 'GOOGLE_APPLICATION_CREDENTIALS'
    customer_id: 'C0xxxxxxx'
    admin_email: '[email protected]'

bundle:
  signing:
    private_key_path: '~/.evidence/keys/private.pem'
  max_size_mb: 50

upload:
  enabled: true
  api_url: 'https://api.evidence-platform.com'
  retention_days: 365

Examples

Weekly Collection with Artifact Upload

name: Weekly Evidence Collection
on:
  schedule:
    - cron: '0 2 * * 1' # Monday at 2 AM UTC

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

      - name: Collect Evidence
        id: collect
        uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence.yaml
          output-path: ./bundles
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: evidence-bundle-${{ steps.collect.outputs.bundle-id }}
          path: ${{ steps.collect.outputs.bundle-path }}
          retention-days: 90

      - name: Notify on Success
        run: |
          echo "Bundle created: ${{ steps.collect.outputs.bundle-path }}"
          echo "Bundle ID: ${{ steps.collect.outputs.bundle-id }}"

Multi-Environment Collection

name: Multi-Environment Evidence
on:
  workflow_dispatch:

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

      - uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence-production.yaml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.PROD_AWS_KEY }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.PROD_AWS_SECRET }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}

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

      - uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence-staging.yaml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.STAGING_AWS_KEY }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.STAGING_AWS_SECRET }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}

Verify and Upload Pipeline

name: Verify and Upload Evidence
on:
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    outputs:
      bundle-path: ${{ steps.collect.outputs.bundle-path }}
    steps:
      - uses: actions/checkout@v4

      - name: Collect Evidence
        id: collect
        uses: evidence-sdk/action@v1
        with:
          command: collect
          config-path: ./evidence.yaml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          EVIDENCE_SIGNING_KEY: ${{ secrets.EVIDENCE_SIGNING_KEY }}

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

      - name: Verify Bundle
        uses: evidence-sdk/action@v1
        with:
          command: verify
          bundle-path: ${{ needs.collect.outputs.bundle-path }}

  upload:
    needs: [collect, verify]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Upload Bundle
        uses: evidence-sdk/action@v1
        with:
          command: upload
          bundle-path: ${{ needs.collect.outputs.bundle-path }}
        env:
          EVIDENCE_API_KEY: ${{ secrets.EVIDENCE_API_KEY }}

Troubleshooting

Error: Config file not found

Make sure your evidence.yaml file is committed to your repository and the path is correct:

- uses: evidence-sdk/action@v1
  with:
    command: collect
    config-path: ./evidence.yaml # Update path if needed

Error: Bundle file not found

For verify/upload commands, ensure the bundle-path points to an existing file:

- uses: evidence-sdk/action@v1
  with:
    command: verify
    bundle-path: ./evidence-bundles/evidence-bundle-*.tar.gz

Error: No bundle file generated

Check that:

1. Your evidence.yaml configuration is valid
2. All required environment variables are set as secrets
3. The CLI has necessary permissions to collect evidence

Error: Verification failed

This typically means:

1. Bundle checksums don't match (file corruption)
2. Signature is invalid (wrong signing key)
3. Bundle format is incorrect

Run with debug logging:

- uses: evidence-sdk/action@v1
  with:
    command: verify
    bundle-path: ./bundle.tar.gz
  env:
    ACTIONS_STEP_DEBUG: true

Security Best Practices

1. Use GitHub Secrets

Never hardcode credentials in workflows:

# BAD - Credentials in plain text
env:
  AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE

# GOOD - Use secrets
env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}

2. Limit Workflow Permissions

Use minimal permissions:

permissions:
  contents: read
  actions: write # Only if uploading artifacts

3. Pin Action Versions

Use specific versions or commit SHAs:

# GOOD - Pinned version
- uses: evidence-sdk/[email protected]

# BETTER - Pinned to commit SHA
- uses: evidence-sdk/action@abc123def456...

# AVOID - Unpinned version
- uses: evidence-sdk/action@main

4. Rotate Signing Keys

Store signing keys securely and rotate regularly:

# Generate new signing key
evidence init --generate-keys

# Update GitHub secret with new key
gh secret set EVIDENCE_SIGNING_KEY < ~/.evidence/keys/private.pem

5. Review Bundle Contents

Before uploading, verify the bundle contains only expected evidence:

- name: Review Bundle
  run: |
    tar -tzf ./evidence-bundle.tar.gz
    tar -xzf ./evidence-bundle.tar.gz -C ./review
    cat ./review/manifest.json

Advanced Usage

Custom CLI Version

Use a specific CLI version:

- uses: evidence-sdk/action@v1
  with:
    command: collect
    cli-version: '1.2.3'

Custom Output Path

Specify where bundles are saved:

- uses: evidence-sdk/action@v1
  with:
    command: collect
    output-path: ./custom/path/bundles

Conditional Upload

Only upload on main branch:

- uses: evidence-sdk/action@v1
  with:
    command: collect
    upload: ${{ github.ref == 'refs/heads/main' }}

Support

• Documentation: https://docs.evidence-sdk.com
• Issues: https://github.com/evidence-sdk/action/issues
• Discussions: https://github.com/evidence-sdk/action/discussions

License

MIT License - see LICENSE file for details.