Skip to content

ADR-026: Dependabot Security Update Strategy

Status

Accepted - 2025-10-01 Updated - 2025-10-24 (Separation of Concerns Architecture) Updated - 2025-10-28 (Removed pip/doc from template to prevent fork caching issues) Updated - 2025-12-19 (Changed Maven schedule from weekly to daily for faster rebasing) Updated - 2026-09-11 (Initialization closes PRs from the inherited template configuration; docker limited to digest and patch updates) Updated - 2026-09-15 (Maven directories restricted to fork-owned Azure paths; shared code arrives through the upstream sync, per ADR-038) Updated - 2026-09-15 (A bump that edits an upstream-owned pom is closed by the validation workflow; groups removed; weekly schedule; no issue on a failed build)

Context

Forks of OSDU services need dependency updates that arrive promptly, do not break compatibility with upstream, and are validated before merge. The engineering system (workflows, actions, the Dockerfile) is maintained in the template and reaches forks through template sync, so a fork's own Dependabot must not also scan .github: doing so produced duplicate PRs and a race during initialization, when a fork briefly inherits the template's configuration before deploy-fork-resources.sh replaces it.

Decision

Dependabot is split by ownership:

  1. The template owns the engineering system. The template's .github/dependabot.yml scans GitHub Actions under .github and the base images in build/.
  2. Forks own application code. The fork configuration deployed from .github/fork-resources/dependabot.yml scans Maven only.
  3. Template sync carries platform updates. Action and Dockerfile bumps merged in the template reach forks through sync-template.yml, never through a fork's Dependabot.
  4. Conservative policy. Fork Maven updates are patch-only; build tooling is pinned by hand.
  5. Only fork-owned bumps merge. Maven writes an inherited version where it is declared, so a bump seen from an Azure pom can land in the root pom.xml or testing/pom.xml. dependabot-validation.yml lists the upstream-owned files a PR changes, using the same action as the ADR-038 check in validate.yml, and closes the PR with a comment when there are any. Dependabot does not reopen a closed version. Shared-code CVEs stay visible in the Security tab and are fixed upstream.

Auto-rebase

Dependabot rebases its open PRs on the scheduled check, on conflict with the target branch, and when a closed PR is reopened. @dependabot rebase on a PR forces an immediate rebase. Fork PRs only touch the Azure poms now, which rarely conflict, so the fork schedule is weekly.

Alternatives Considered

Disabling Dependabot leaves security fixes to manual monitoring. Allowing minor and major updates broke compatibility with upstream OSDU too often. Security-only updates accumulate technical debt. All three were rejected in favour of the patch-only, grouped policy.

Implementation

Template repository (.github/dependabot.yml): two ecosystems, both targeting main with the dependencies label and a limit of 5 open PRs.

  • github-actions on /.github, daily at 08:00, all actions grouped, minor and patch only, with a 7-day cooldown
  • docker on /build, daily at 08:30, grouped, digest and patch updates only, for the base images in the Dockerfiles the template owns (ADR-037); major and minor image changes (the Java release) and the App Insights agent, an ADD with a checksum rather than a FROM, stay manual

There is no pip ecosystem for doc/. A fork inherits this file until deploy-fork-resources.sh replaces it, and Dependabot caches the ecosystem list, so a doc/ entry made forks fail on a directory they do not have.

The same inheritance means Dependabot runs this file in a new repository until initialization replaces it, starting with the initial commit, and can open PRs against build/ or .github. It never revisits them after the swap, so init-complete.yml closes every open Dependabot PR outside the fork's maven ecosystem once the fork configuration lands.

Fork repositories (.github/fork-resources/dependabot.yml, deployed to .github/dependabot.yml): one maven ecosystem, weekly on Monday at 09:00, targeting main with the dependencies label.

  • Directories: /provider/*-azure, /testing/*-test-azure. Shared code (/, /*-core, /*-acceptance-test, /testing, /testing/*-test-core) is upstream-owned and arrives through the upstream sync, not Dependabot (ADR-038).
  • Minor and major updates ignored for every dependency
  • Build tooling ignored entirely: JaCoCo, git-commit-id, Lombok, Maven plugins, the Spring Boot Maven plugin
  • No groups: a grouped PR that reaches an upstream-owned pom is closed whole, which would take its fork-owned bumps down with it

Validation (.github/template-workflows/dependabot-validation.yml): runs on PRs from dependabot[bot] against main, fork_integration, and fork_upstream, skipping .github and documentation paths. It first closes any PR that edits an upstream-owned file, then builds the Java project and runs a validate-only Docker build. A failed build is reported on the PR's checks, where the code-owner review already puts it in front of a reviewer; no issue is opened. There is no auto-approve and no auto-merge; a human merges every Dependabot PR.

Update flow

Template (azure/osdu-spi):
  08:00 → Dependabot scans /.github, opens a grouped actions PR
  08:30 → Dependabot scans /build, opens a base-image PR
         → platform team merges
  next sync-template run → PR in every fork with the updated workflows/Dockerfile

Fork (service repository):
  Monday 09:00 → Dependabot scans the Azure poms, opens one patch PR per dependency
         → dependabot-validation closes a PR that edits an upstream-owned pom
         → otherwise builds and validates the image; the result is the PR's check
         → human reviews and merges

Consequences

Forks depend on the template for every workflow and action update. Automated PRs still need review time, and a patch update can conflict with a fork's local modifications. Because only patch updates are automated, minor and major upgrades have to be scheduled by hand.

References

← ADR-025 | Catalog | ADR-027 →