Skip to content

ADR-026: Dependabot Security Update Strategy

Status

Accepted - 2025-10-01 Updated - 2025-10-24 (Separation of Concerns Architecture)

Context

Fork repositories managing OSDU services face unique challenges with dependency management:

  1. Security Vulnerabilities: Dependencies need timely security updates to prevent exploits
  2. Upstream Compatibility: Updates must not break compatibility with upstream OSDU
  3. Validation Requirements: All dependency updates need thorough testing before merge
  4. Update Frequency: Balance between security responsiveness and stability
  5. Fork-Specific Dependencies: Local enhancements may have additional dependencies
  6. Engineering System Updates: Workflows and actions maintained separately from application code

GitHub's Dependabot provides automated dependency updates, but the fork management template needed a strategy that: - Ensures security updates are applied promptly - Maintains compatibility with the three-branch strategy - Provides appropriate validation for different update types - Handles both upstream and fork-specific dependencies - Separates platform concerns (workflows) from application concerns (code dependencies) - Eliminates race conditions during fork initialization

Decision

Implement a Separation of Concerns Dependabot Strategy with:

  1. Template Owns Engineering System: Template repository monitors .github (workflows, actions) and doc (documentation)
  2. Forks Own Application Code: Fork repositories monitor Maven dependencies ONLY
  3. Template Sync Propagates Platform Updates: Engineering system updates flow via sync-template workflow
  4. Grouped Updates: Related dependencies updated together to reduce PR noise
  5. Conservative Update Policy: Patch and minor updates only, major versions require manual review
  6. No Duplicate PRs: Forks never scan .github, eliminating race conditions and duplicate updates

Rationale

Security-First Approach

  1. Vulnerability Mitigation: Security updates applied within 48 hours of disclosure
  2. Automated Detection: GitHub Security Advisory database integration
  3. Priority Handling: Security PRs labeled and prioritized appropriately
  4. Compliance Requirements: Meet enterprise security update SLAs

Controlled Update Strategy

  1. Stability Focus: Conservative update policy prevents breaking changes
  2. Validation Gates: All updates must pass build, test, and integration checks
  3. Grouped Updates: Reduces PR proliferation and review overhead
  4. Manual Major Versions: Breaking changes require human review and testing

Alternatives Considered

1. Disable Dependabot Entirely

  • Pros: No automated PRs, full manual control
  • Cons: Miss critical security updates, increased security risk
  • Decision: Rejected - Security risk too high

2. Aggressive Update Strategy

  • Pros: Always latest versions, newest features
  • Cons: Frequent breaks, incompatibility with upstream OSDU
  • Decision: Rejected - Stability more important than latest features

3. Security-Only Updates

  • Pros: Minimal changes, only critical updates
  • Cons: Miss important bug fixes, technical debt accumulation
  • Decision: Rejected - Need balance between security and maintenance

4. Manual Security Monitoring

  • Pros: Human judgment for each update
  • Cons: Slow response time, human error, doesn't scale
  • Decision: Rejected - Automation essential for timely updates

Implementation Details

Dependabot Configuration

Template Repository (.github/dependabot.yml): 

version: 2
updates:
  # Engineering System - Template Responsibility
  - package-ecosystem: "github-actions"
    directory: "/.github"  # Monitors ALL .github subdirectories recursively
    schedule:
      interval: "daily"
      time: "08:00"
    groups:
      github-actions:
        patterns:
          - "*"
        update-types:
          - "minor"
          - "patch"

  # Documentation - Template Responsibility
  - package-ecosystem: "pip"
    directory: "/doc"
    schedule:
      interval: "daily"
      time: "08:00"

Fork Repositories (.github/fork-resources/dependabot.yml → .github/dependabot.yml): 

version: 2
updates:
  # NO GitHub Actions monitoring - Receives via sync-template!

  # Maven Dependencies - Application Code Only
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "sunday"
      time: "09:00"
    groups:
      spring:
        patterns:
          - "org.springframework*"
        update-types:
          - "patch"
    # Additional Maven configs for /<service>-core and /provider/<service>-azure

Validation Workflow

# dependabot-validation.yml
name: Dependabot Validation
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  validate:
    if: github.actor == 'dependabot[bot]'
    steps:
      - Auto-approve security updates
      - Run comprehensive test suite
      - Check for breaking changes
      - Validate against upstream OSDU

Update Flow Architecture

Template Repository (azure/osdu-spi):
  Day 1 08:00 → Dependabot scans /.github
             → Finds actions/checkout@v4 → v5
             → Creates PR in template
  Day 1 10:00 → Platform team merges PR
  Day 2 08:00 → sync-template workflow runs
             → Creates PRs in all forks with updated workflows

Fork Repositories (danielscholl-osdu/*):
  Day 2 08:00 → Receive sync-template PR with workflow updates
             → Review and merge (engineering system updates)
  Sunday 09:00 → Dependabot scans Maven dependencies
              → Creates PRs for Spring Boot, Jackson, etc.
              → NO GitHub Actions scanning (eliminates duplicates)

Update Groups

Repository Ecosystem Update Frequency Managed By
Template GitHub Actions Daily Template Dependabot
Template Python/pip Daily Template Dependabot
Forks Maven (root) Weekly Fork Dependabot
Forks Maven (core) Weekly Fork Dependabot
Forks Maven (provider) Weekly Fork Dependabot
Forks GitHub Actions N/A Template sync-template

Label Strategy

  • dependencies - All Dependabot PRs
  • security - Security-related updates
  • auto-merge - Safe to merge automatically
  • needs-review - Requires human review
  • breaking-change - Potentially breaking update

Consequences

Positive

  • Improved Security Posture: Vulnerabilities patched within 48 hours via template
  • Eliminated Race Conditions: Forks don't scan .github, no timing issues during init
  • No Duplicate PRs: Single source of truth for engineering system updates
  • Clear Separation of Concerns: Template owns platform, forks own application code
  • Reduced Manual Work: Automated dependency updates save developer time
  • Scalable Architecture: 1 template update → N fork updates automatically
  • Consistent Validation: All updates go through same validation process
  • Audit Trail: Complete history of dependency updates in GitHub
  • OSDU Compatibility: Conservative approach maintains upstream compatibility

Negative

  • PR Noise: Regular automated PRs require attention
  • Validation Overhead: All updates require CI/CD resources
  • Potential Conflicts: Updates may conflict with local modifications
  • Template Dependency: Forks rely on template for workflow/action updates

Neutral

  • GitHub Dependency: Relies on GitHub's Dependabot service
  • Update Lag: Conservative strategy means not always latest versions
  • Two-Track Updates: Engineering system (daily) vs application code (weekly)

Success Criteria

  • Security vulnerabilities patched within 48 hours of disclosure
  • < 10 open Dependabot PRs at any time
  • 95% of security updates auto-merge successfully
  • Zero breaking changes from automated updates
  • Build success rate > 90% for Dependabot PRs
  • Clear audit trail of all dependency updates

Monitoring and Metrics

Key Metrics

  • Time to Patch: Hours from CVE disclosure to PR merge
  • PR Success Rate: Percentage of Dependabot PRs that pass validation
  • Auto-merge Rate: Percentage of PRs merged automatically
  • Breaking Change Rate: Frequency of updates causing failures

Alerts

  • Security updates pending > 48 hours
  • Dependabot PRs failing repeatedly
  • Critical vulnerabilities detected
  • Update limit reached (10 PRs)

Integration Points

With Build System (ADR-025)

  • Dependabot updates trigger Maven builds
  • JaCoCo coverage must remain above thresholds
  • Community repository dependencies validated

With Validation Workflow

  • Comprehensive testing of dependency updates
  • Integration testing with upstream OSDU
  • Automated approval for safe updates

With Release Management (ADR-004)

  • Dependency updates reflected in release notes
  • Security patches trigger patch releases
  • Changelog includes dependency updates

Future Evolution

Potential Enhancements

  1. Smart Grouping: ML-based dependency grouping for optimal updates
  2. Risk Scoring: Automated risk assessment for updates
  3. Rollback Automation: Automatic rollback of problematic updates
  4. Custom Security Policies: Organization-specific security requirements
  5. Cross-Repository Coordination: Synchronized updates across fork family

Integration Opportunities

  • Integration with security scanning tools
  • Custom validation for OSDU-specific dependencies
  • Automated compatibility testing with upstream
  • Security update notifications to Slack/Teams

References

← ADR-025 | Catalog | ADR-027 →