Documentation
ReferenceConfigurationUpload Configuration

Upload Configuration

Complete schema reference for configuring automatic bundle uploads in evidence.yaml.

Schema

upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  api_key_env: EVIDENCE_API_KEY
  organization_id: org_abc123
  retention_days: 365
  tags:
    environment: production
    team: security
    compliance: soc2
  verify_before_upload: true
  delete_after_upload: false

All fields optional - Upload disabled by default.

Fields Reference

FieldTypeRequiredDefaultDescription
enabledbooleanNofalseEnable automatic upload after collection
api_urlstringNohttps://api.evidence-platform.comevidence platform API endpoint
api_key_envstringNoEVIDENCE_API_KEYEnvironment variable containing API key
organization_idstringNo(from API key)Organization ID for multi-org accounts
retention_daysnumberNo365Bundle retention period in days
tagsobjectNo{}Metadata tags for bundle organization
verify_before_uploadbooleanNotrueVerify bundle integrity before upload
delete_after_uploadbooleanNofalseDelete local bundle after successful upload
timeout_secondsnumberNo300Upload timeout in seconds
retry_attemptsnumberNo3Number of retry attempts on failure

Basic Configuration

Minimal Upload

Enable upload with defaults:

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
upload:
  enabled: true

Requires environment variable:

export EVIDENCE_API_KEY=evd_api_your_key_here

Behavior:

  1. Collect evidence
  2. Create signed bundle
  3. Verify bundle locally
  4. Upload to platform
  5. Keep local copy

Manual Upload (Default)

Upload disabled (manual upload with CLI):

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
upload:
  enabled: false  # or omit upload section entirely

Manual upload later:

evidence upload evidence-bundle-*.tar.gz

API Configuration

Custom API Endpoint

For self-hosted or staging environments:

upload:
  enabled: true
  api_url: https://evidence.internal.company.com/api

Use cases:

  • Self-hosted evidence platform
  • Staging environment
  • Development testing

Environment-Specific Endpoints

Development:

upload:
  enabled: true
  api_url: http://localhost:3000/api

Staging:

upload:
  enabled: true
  api_url: https://api.staging.evidence-platform.com

Production:

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

Custom API Key Variable

Use different environment variable:

upload:
  enabled: true
  api_key_env: CUSTOM_API_KEY

Set environment variable:

export CUSTOM_API_KEY=evd_api_your_key_here

Organization Configuration

Multi-Organization Accounts

Override organization for multi-org accounts:

upload:
  enabled: true
  organization_id: org_staging_123

Use case: API key has access to multiple organizations

Default behavior: Uses organization ID from API key metadata

Organization from Environment

upload:
  enabled: true
  organization_id: ${EVIDENCE_ORG_ID}

Set environment variable:

export EVIDENCE_ORG_ID=org_production_456

Retention Configuration

Default Retention (1 Year)

upload:
  enabled: true
  retention_days: 365  # Default: 1 year

Behavior:

  • Bundle auto-deleted after 365 days
  • Countdown starts from upload date
  • Warning notification before deletion
  • Can extend before expiration

Extended Retention

For SOC 2 Type II (requires 3-6 months, often keep longer):

upload:
  enabled: true
  retention_days: 730  # 2 years

Use case: Long audit periods, regulatory requirements

Short Retention

For development or testing:

upload:
  enabled: true
  retention_days: 30  # 30 days

Warning: Not suitable for compliance purposes

Permanent Retention

Keep bundles indefinitely:

upload:
  enabled: true
  retention_days: 0  # 0 = no expiration

Warning: Storage costs will accumulate

Tagging Configuration

Basic Tags

Organize bundles with metadata tags:

upload:
  enabled: true
  tags:
    environment: production
    team: security

Platform features:

  • Filter bundles by tag
  • Search by tag
  • Group reports by tag
  • Tag-based notifications

Comprehensive Tagging

upload:
  enabled: true
  tags:
    environment: production
    team: security
    compliance: soc2
    region: us-east-1
    application: backend-api
    cost_center: engineering
    owner: security-team@acme.com

Best practices:

  • Use consistent tag keys across bundles
  • Include ownership information
  • Tag by environment for easy filtering
  • Add application/service identifiers

Dynamic Tags

Use environment variables for dynamic tags:

upload:
  enabled: true
  tags:
    environment: ${ENVIRONMENT}
    git_commit: ${GITHUB_SHA}
    build_number: ${GITHUB_RUN_NUMBER}

GitHub Actions:

env:
  ENVIRONMENT: production
  GITHUB_SHA: ${{ github.sha }}
  GITHUB_RUN_NUMBER: ${{ github.run_number }}

Verification Options

Verify Before Upload (Default)

upload:
  enabled: true
  verify_before_upload: true  # Default

Process:

  1. Create bundle
  2. Verify checksums (SHA-256)
  3. Verify signature (Ed25519)
  4. If valid → upload
  5. If invalid → abort upload

Recommended: Always enable for production

Skip Local Verification

Not recommended, but available:

upload:
  enabled: true
  verify_before_upload: false

Warning: Platform still verifies server-side, but you'll waste upload bandwidth if bundle is invalid

Use case: Already verified bundle separately

Upload Behavior

Keep Local Copy (Default)

upload:
  enabled: true
  delete_after_upload: false  # Default

Behavior:

  • Upload bundle to platform
  • Keep local copy in output directory
  • Useful for backup or secondary verification

Delete After Upload

Clean up local bundles automatically:

upload:
  enabled: true
  delete_after_upload: true

Behavior:

  • Upload bundle to platform
  • Verify upload succeeded
  • Delete local copy

Use cases:

  • CI/CD pipelines (artifact storage in platform)
  • Limited local storage
  • Security requirement to not keep bundles locally

Warning: Ensure platform upload succeeded before deleting

Timeout Configuration

upload:
  enabled: true
  timeout_seconds: 600  # 10 minutes

Default: 300 seconds (5 minutes)

Increase timeout for:

  • Large bundles (50+ MB)
  • Slow network connections
  • Multi-region uploads

Retry Configuration

upload:
  enabled: true
  retry_attempts: 5  # Retry up to 5 times

Default: 3 retry attempts

Retry behavior:

  • Exponential backoff (1s, 2s, 4s, 8s, 16s)
  • Retries on network errors
  • Retries on 5xx server errors
  • No retry on 4xx client errors (invalid API key, etc.)

Complete Examples

Development Configuration

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/dev.pem
upload:
  enabled: true
  api_url: http://localhost:3000/api
  retention_days: 7
  tags:
    environment: development
  delete_after_upload: false

Production Configuration

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2
sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos: '*'
  aws:
    mode: env
    region: us-east-1
    cloudtrail:
      trails:
        - production-audit-trail
bundle:
  signing:
    private_key_path: /etc/evidence/keys/production.pem
    key_id: prod-2026-01
  output_path: /var/evidence/bundles
  max_size_mb: 100
upload:
  enabled: true
  api_url: https://api.evidence-platform.com
  retention_days: 730
  tags:
    environment: production
    team: security
    compliance: soc2
    application: backend-api
  verify_before_upload: true
  delete_after_upload: false
  timeout_seconds: 600
  retry_attempts: 5

CI/CD Configuration

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
  - CC7.2
sources:
  github:
    mode: token
    token_env: GITHUB_TOKEN
    org: acme
    repos: '*'
bundle:
  signing:
    private_key_path: ${RUNNER_TEMP}/signing-key.pem
  output_path: ${GITHUB_WORKSPACE}/artifacts
upload:
  enabled: true
  retention_days: 365
  tags:
    environment: ${ENVIRONMENT}
    git_commit: ${GITHUB_SHA}
    workflow_run: ${GITHUB_RUN_NUMBER}
    triggered_by: ${GITHUB_ACTOR}
  verify_before_upload: true
  delete_after_upload: true  # Clean up CI artifacts

Validation

Missing API Key

upload:
  enabled: true

Error (at collection time):

✗ Upload failed

Error: API key not found

Set EVIDENCE_API_KEY environment variable:
  export EVIDENCE_API_KEY=evd_api_your_key_here

Or configure custom variable:
  upload:
    api_key_env: CUSTOM_KEY_NAME

Invalid API Key Format

upload:
  enabled: true

Environment variable:

export EVIDENCE_API_KEY=invalid_key

Error:

✗ Authentication failed

Error: Invalid API key format

API keys must start with 'evd_api_'

Create API key in platform:
  Settings → API Keys → Create API Key

Invalid Retention Days

upload:
  enabled: true
  retention_days: -30  # ❌ Negative value

Error:

Configuration validation failed:
  - upload.retention_days: must be >= 0 (got -30)

Invalid Timeout

upload:
  enabled: true
  timeout_seconds: 1000000  # ❌ Too large

Error:

Configuration validation failed:
  - upload.timeout_seconds: must be <= 3600 (got 1000000)
  - Maximum timeout: 1 hour (3600 seconds)

Upload Process

When upload.enabled: true and you run evidence collect:

Step 1: Collection

Collecting evidence...
  ✓ GitHub (3 artifacts)
  ✓ AWS (2 artifacts)

✓ Collection complete (5 artifacts in 12.3s)

Step 2: Bundle Creation

Creating bundle...
  ✓ Manifest generated
  ✓ Checksums computed
  ✓ Signature created

✓ Bundle created: evidence-bundle-20260109-123456.tar.gz (35.1 KB)

Step 3: Local Verification (if enabled)

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

✓ Bundle verified

Step 4: Upload

Uploading to evidence platform...
  ✓ Authenticated (organization: acme)
  ✓ Upload complete (2.3s, 35.1 KB)
  ✓ Verified on platform

✓ Upload successful

Bundle ID: bundle_abc123def456
Platform URL: https://app.evidence-platform.com/bundles/bundle_abc123def456

Step 5: Timeline Update

Timeline updated:
  Controls: CC6.1, CC6.6, CC7.2
  Period: 2026-01-09
  Status: Evidence collected

Next collection: 2026-02-09 (in 31 days)

Troubleshooting

Authentication Failed

Symptom:

✗ Upload failed

Error: Authentication failed (HTTP 401)

Invalid or expired API key.

Solutions:

  1. Verify API key is set:

    echo $EVIDENCE_API_KEY

  2. Check API key format:

    • Must start with evd_api_
    • Should be 32+ characters

  3. Create new API key:

    • Go to platform → Settings → API Keys
    • Create new key with bundles:upload permission
    • Update environment variable

  4. Check key hasn't been revoked:

    • Review API keys in platform dashboard
    • Verify key status is "Active"

Upload Timeout

Symptom:

✗ Upload failed

Error: Request timeout after 300s

Network error: Connection timeout

Solutions:

  1. Increase timeout:

    upload:
  timeout_seconds: 600

  2. Check bundle size:

    ls -lh evidence-bundle-*.tar.gz

  3. Reduce bundle size:

    bundle:
  max_size_mb: 25
sources:
  aws:
    log_groups:
      - /aws/lambda/api  # Limit scope

  4. Check network connectivity:

    curl -I https://api.evidence-platform.com

Rate Limit Exceeded

Symptom:

✗ Upload failed

Error: Rate limit exceeded (HTTP 429)

Try again in 60 seconds.

Solutions:

  1. Wait for rate limit reset:

    sleep 60
evidence upload evidence-bundle-*.tar.gz

  2. Check frequency:

    • Recommended: Once per day or week
    • Not recommended: Multiple uploads per minute

  3. Contact platform support:

    • For higher rate limits
    • Enterprise plans available

Platform Verification Failed

Symptom:

✓ Upload complete
✗ Platform verification failed

Error: Signature verification failed on platform

Bundle was uploaded but rejected by platform.

Solutions:

  1. Register public key in platform:

    • Go to Settings → Signing Keys
    • Upload public key from ~/.evidence/keys/public.pem
    • Verify key fingerprint matches

  2. Check key fingerprint:

    openssl pkey -pubin -in ~/.evidence/keys/public.pem -outform DER | \
  openssl dgst -sha256 -binary | base64

  3. Re-upload bundle:

    evidence upload evidence-bundle-*.tar.gz

Best Practices

1. Use Environment Variables for Secrets

✅ Good:

upload:
  enabled: true
  api_key_env: EVIDENCE_API_KEY

❌ Bad:

upload:
  enabled: true
  api_key: evd_api_hardcoded_key  # ❌ Never hardcode

2. Tag Bundles Consistently

✅ Good:

upload:
  tags:
    environment: production
    team: security
    compliance: soc2

Benefits:

  • Easy filtering in platform
  • Better organization
  • Clearer ownership

3. Set Appropriate Retention

SOC 2 Type I: 365 days minimum SOC 2 Type II: 730 days recommended Development: 30 days sufficient

4. Enable Verification

✅ Good:

upload:
  verify_before_upload: true

Benefit: Catch issues before wasting upload bandwidth

5. Configure Retries

✅ Good:

upload:
  retry_attempts: 3

Benefit: Handle transient network issues automatically

See Also

Bundle Configuration

Complete schema reference for configuring evidence bundle options in evidence.yaml.

GitHub Connector

Complete reference for collecting SOC 2 evidence from GitHub using the evidence SDK.

On this page

SchemaFields ReferenceBasic ConfigurationMinimal UploadManual Upload (Default)API ConfigurationCustom API EndpointEnvironment-Specific EndpointsCustom API Key VariableOrganization ConfigurationMulti-Organization AccountsOrganization from EnvironmentRetention ConfigurationDefault Retention (1 Year)Extended RetentionShort RetentionPermanent RetentionTagging ConfigurationBasic TagsComprehensive TaggingDynamic TagsVerification OptionsVerify Before Upload (Default)Skip Local VerificationUpload BehaviorKeep Local Copy (Default)Delete After UploadTimeout ConfigurationRetry ConfigurationComplete ExamplesDevelopment ConfigurationProduction ConfigurationCI/CD ConfigurationValidationMissing API KeyInvalid API Key FormatInvalid Retention DaysInvalid TimeoutUpload ProcessStep 1: CollectionStep 2: Bundle CreationStep 3: Local Verification (if enabled)Step 4: UploadStep 5: Timeline UpdateTroubleshootingAuthentication FailedUpload TimeoutRate Limit ExceededPlatform Verification FailedBest Practices1. Use Environment Variables for Secrets2. Tag Bundles Consistently3. Set Appropriate Retention4. Enable Verification5. Configure RetriesSee Also