Migrating to Dependency-Track v5

Dependency-Track v5 is the next major version of the project, previously developed under the codename Hyades. For what is actually new in v5, including architecture, schema, configuration, and API surface, see About changes in v5.

This document covers the GA cutover itself. It describes what changes for operators, contributors, and downstream consumers as v5 moves to GA, and what your options are for staying on v4.

Contents

• Phases
• What is moving
  • Source repositories
  • Container images
• Tag policy
  • :latest
  • :snapshot
  • v5 tags
• Pin recommendations
• Action items by audience
  • Operators
    • Required action today
    • v4 maintenance window
    • After v4 EOL
    • Migrating to v5
    • Helm
  • Contributors and PR authors
    • If you have an open PR
    • Re-targeting a PR's base branch
    • Moving a local branch to the new repo
    • Forks
    • Where things live after cutover
    • Issues and discussions on hyades-* repos
    • ADRs (new in v5)
• Historical artifacts
• What is not changing

Phases

The cutover proceeds in ordered phases. Timing is best-effort and community-driven. Each phase advances only when its preconditions are met. Do not plan around fixed dates.

Phase	Precondition	What happens
Announcement	Maintainers agree the cutover is imminent	Public notice. v4 master enters freeze on a date named in the notice.
Cutover	v5 5.0.0-rc.1 ready to publish	v4 master (both repos) renamed to v4-master-archived. v5 imported as main. RC published. hyades-* repos archived.
GA	RC soak completes with no blockers	v5 5.0.0 GA published.
v4 EOL	At least ~6 months elapsed since v5 GA	v4 patches stop. :snapshot discontinued. :latest flips to v5.

Each phase is announced ahead of time on the GitHub Discussions, and #dependency-track channel in the OWASP Slack.

What is moving

Source repositories

Before (v4 / pre-GA v5)	After (v5 GA onwards)
DependencyTrack/dependency-track (v4)	DependencyTrack/dependency-track:4.14.x (v4)
DependencyTrack/dependency-track:master	Renamed to :v4-master-archived (frozen, no merges accepted)
DependencyTrack/frontend (v4)	DependencyTrack/frontend:4.14.x (v4)
DependencyTrack/frontend:master	Renamed to :v4-master-archived (frozen, no merges accepted)
DependencyTrack/hyades-apiserver (v5 dev)	DependencyTrack/dependency-track:main (v5)
DependencyTrack/hyades-frontend (v5 dev)	DependencyTrack/frontend:main (v5)

hyades-apiserver and hyades-frontend are archived at cutover. They remain readable. No new pushes, no new issues, no new PRs.

Container images

Before	After
dependencytrack/hyades-apiserver:<tag>	dependencytrack/apiserver:<tag>
ghcr.io/dependencytrack/hyades-apiserver	ghcr.io/dependencytrack/apiserver
dependencytrack/hyades-frontend:<tag>	dependencytrack/frontend:<tag>
ghcr.io/dependencytrack/hyades-frontend	ghcr.io/dependencytrack/frontend

v4 images (dependencytrack/apiserver, dependencytrack/frontend, dependencytrack/bundled) do not change name. v4 has always published to these names. Only the pre-GA v5 (hyades-*) images are renamed.

Tag policy

:latest and :snapshot deliberately do not flip on the GA date. This is to prevent unpinned v4 deployments from silently jumping to v5 on the next docker pull and breaking.

:latest

Period	Resolves to
Today through v4 EOL	Latest v4 release
After v4 EOL	Latest v5 release

If you run :latest in production today, pin to an explicit version before v4 EOL. After v4 EOL, :latest advances across the major boundary in one pull.

:snapshot

Tag	Period	Resolves to
:snapshot	Today through v4 EOL	v4 nightly
:snapshot	After v4 EOL	Discontinued
:4-snapshot	From cutover onwards	v4 nightly (frozen at EOL)
:5-snapshot	From v5 GA onwards	v5 nightly

:snapshot is not flipped to v5 at v4 EOL. Migrate to :4-snapshot or :5-snapshot explicitly.

v5 tags

Tag	Resolves to
:5.x.y	Exact v5 release. Immutable.
:5.x.y-rc.N	Exact RC. Immutable.
:5-snapshot	v5 main nightly
:latest	See :latest.

No floating major (:5) or minor (:5.0) tags are published. This matches v4's tagging surface and steers operators toward digest or exact-version pins (see Pin recommendations).

Pin recommendations

For production, in order of preference:

1. Digest pin (@sha256:...). Strongest guarantee. Survives tag mutation, repo deletion, and registry mirroring.
2. Exact version (:4.14.3 or :5.0.0). Survives the cutover unchanged.

Use Renovate, Dependabot, or equivalent to bump exact pins on a schedule you control.

Do not use :latest or :snapshot in production. Both move under you without notice.

Action items by audience

Operators

Required action today

None, if you pin image tags by an exact version or digest. v4 keeps shipping on its existing image names and tags until v4 EOL (~6 months post-v5 GA).

If you currently pull :latest or :snapshot, switch before v4 EOL:

Today	Pin to
dependencytrack/apiserver:latest	An exact version (e.g. :4.14.3) or a digest
dependencytrack/apiserver:snapshot	:4-snapshot or a digest
dependencytrack/frontend:latest	An exact version (e.g. :4.14.3) or a digest
dependencytrack/frontend:snapshot	:4-snapshot or a digest

:4-snapshot becomes available at cutover. Until then, pin to a digest to escape :snapshot.

v4 maintenance window

• v4 continues to receive 4.14.x patch releases. There will be no further v4 minor releases (no 4.15.0).
• Patch cadence is best-effort and community-driven, focused on security and high-severity fixes.
• File v4 bugs against DependencyTrack/dependency-track with the v4 label.

After v4 EOL

• No further patches, including for CVEs in v4 itself or its dependencies.
• New issues that apply only to v4 are closed with a pointer to v5. Existing v4-labeled issues remain as-is and readable for reference.

Migrating to v5

• About changes in v5 for the architectural, schema, and configuration deltas.
• Migrating from v4 to v5 for the step-by-step migrator procedure, prerequisites, and post-migration audit checklist.
• Rehearsing the v4 migration to dry-run against a production copy before scheduling the cutover.
• Running v4 and v5 in parallel for parallel-validation strategies.

Helm

The official chart updates together with v5 GA. See helm-charts. Diff your values file against the v5 chart defaults before bumping.

Contributors and PR authors

If you have an open PR

Re-target your PR before cutover. If you do not, the PR survives but ends up against v4-master-archived, which accepts no merges. You will have to re-target it yourself afterwards.

Against dependency-track:master (pre-cutover v4 repo):

• v4 patch: re-target the base branch to 4.14.x (see re-targeting below).
• v5-bound: close and re-open against hyades-apiserver:main (pre-cutover) or dependency-track:main (post-cutover). Link the original PR in the new description.

Against hyades-apiserver:main or hyades-frontend:main:

• Pre-cutover: business as usual. Land before cutover if you can.
• At cutover: the repo is archived. Existing PRs are not auto-migrated and cannot be merged. Re-open against dependency-track:main (or frontend:main) once v5 GA is published.

Re-targeting a PR's base branch

GitHub UI: open the PR, click Edit next to the title, pick the new base branch. Works only if the new base lives in the same repo. For cross-repo moves (hyades-apiserver -> dependency-track), open a new PR.

Moving a local branch to the new repo

After cutover, point your fork and clone at dependency-track. The archived hyades-apiserver remote still works read-only but will not accept pushes.

# 1. Rename your fork on GitHub: Settings -> Repository name -> "dependency-track"
#    (GitHub keeps redirects, but update the remote anyway.)

# 2. Update the upstream remote
git remote set-url upstream https://github.com/DependencyTrack/dependency-track.git

# 3. Update your fork remote
git remote set-url origin git@github.com:<you>/dependency-track.git

# 4. Fetch the new default branch and rebase your work
git fetch upstream
git rebase upstream/main

# 5. Push and open the PR against dependency-track:main
git push -u origin <your-branch>

Forks

GitHub does not auto-rename or auto-archive forks.

• Your fork still exists under its old name and still tracks the archived repo.
• Rename it via Settings -> Repository name to keep PRs tidy.
• Branches you pushed before cutover are preserved.

Where things live after cutover

Concern	Location
v5 apiserver code, issues, PRs	DependencyTrack/dependency-track (branch main)
v5 frontend code, issues, PRs	DependencyTrack/frontend (branch main)
v4 maintenance patches	DependencyTrack/dependency-track (branch 4.14.x)
CONTRIBUTING.md, SECURITY.md	DependencyTrack/dependency-track:main (root)
ADRs	DependencyTrack/dependency-track:main under docs/adr/
Helm charts	DependencyTrack/helm-charts (unaffected)
User docs	DependencyTrack/docs (unaffected)

Issues and discussions on hyades-* repos

• Both repos are archived at cutover. Existing issues and discussions stay readable but become read-only.
• Open issues are not auto-migrated. Maintainers will move the ones they judge relevant for v5 to DependencyTrack/dependency-track at their own discretion. No guarantees on which or when.
• If your issue is not moved, and you believe it should be, you have two options:
  • Ask a maintainer to move it via OWASP Slack #dependency-track or GitHub Discussions, linking the original.
  • Re-file on DependencyTrack/dependency-track and link the old issue.
• v4 bug reports go on DependencyTrack/dependency-track with the v4 label.

ADRs (new in v5)

v5 introduces Architecture Decision Records. Substantial changes now require an ADR that reaches Accepted before the implementation PR merges. v4 had no such requirement. See CONTRIBUTING.md#architecture-decision-records for trigger criteria.

Historical artifacts

What is not changing

To keep expectations grounded:

• The Helm chart repository (DependencyTrack/helm-charts) is not renamed or archived.
• The documentation repository (DependencyTrack/docs) is not renamed.
• The project website (dependencytrack.org) does not change URL.
• The OWASP project page does not change URL.