Allow DD_RELEASE_NOTES_GITHUB_TOKEN to override source-repo "trust" for release-notes lookups (and document narrow scoping)

[steilerDev]

Summary

When the release-notes source repo is resolved from an untrusted source (an operator-set dd.source.repo container label, a persisted container.sourceRepo fallback, or a live Docker Hub metadata lookup), the GitHub auth token is unconditionally suppressed — including the dedicated DD_RELEASE_NOTES_GITHUB_TOKEN, not just the GHCR fallback. There is no configuration or env override to opt back in.

This makes authenticated release-notes lookups impossible for the common case of a third-party Docker Hub image that lacks OCI source labels, where the operator can only supply the repo via a container label. The operator is permanently capped at the unauthenticated GitHub API limit (60 req/h, public repos only), even when they have deliberately created a narrowly-scoped, read-only-public token whose leakage would be harmless.

Current behavior (v1.5.0)

The trusted flag is purely structural — decided by where the repo string came from — and short-circuits at the container label:

• app/release-notes/index.ts:223-228 — a container-level dd.source.repo returns { trusted: false } immediately, with no comparison against the image's OCI labels.
• app/release-notes/index.ts:352-354 — trusted is passed straight through as allowToken:

  const releaseNotes = await provider.fetchByTag(sourceRepo, tag, getGithubToken(), {
    allowToken: trusted,
  });

• app/release-notes/providers/GithubProvider.ts:186-190 — when allowToken === false, both the explicit DD_RELEASE_NOTES_GITHUB_TOKEN and the GHCR fallback are dropped:

  const allowToken = options?.allowToken !== false;
  const effectiveToken = allowToken ? (token ?? getGhcrTokenFallback()) : undefined;

The behavior is documented as intentional in content/docs/current/configuration/watchers/index.mdx:757.

Why this is a problem

The threat model — a malicious container spoofing dd.source.repo to exfiltrate a high-scope token to an attacker-controlled repo — is legitimate for the GHCR fallback token, which the operator provisioned for a different purpose and may be broadly scoped. But it should not force the same restriction onto a token the operator created specifically for release notes. An operator who scopes that token to read-only public access has explicitly accepted the (negligible) risk, and there is currently no way to express that intent.

Proposed change

Treat the presence of a dedicated DD_RELEASE_NOTES_GITHUB_TOKEN as an explicit operator opt-in to use that token regardless of source trust:

• When DD_RELEASE_NOTES_GITHUB_TOKEN is set, send it even for untrusted (container-label / Docker Hub / persisted) sources.
• Keep the GHCR fallback (getGhcrTokenFallback()) gated by trusted as it is today — only the explicitly-configured release-notes token gets the override. This preserves the original protection for the broadly-scoped GHCR credential while honoring deliberate operator intent.

(Alternatively, a separate explicit flag such as DD_RELEASE_NOTES_TRUST_CONTAINER_LABELS=true would also solve it, but overloading the dedicated token is cleaner — configuring it is already the explicit signal.)

Docs request

Please document this feature explicitly in the release-notes / GHCR configuration docs, including precise instructions to narrowly scope the token so operators can opt in safely. Concretely:

• A classic PAT scoped to public_repo only (no other scopes), or
• A fine-grained PAT with read-only Contents access limited to public repositories and no account/repo write permissions.

Make clear that this token — unlike the GHCR fallback — is sent even for operator-supplied dd.source.repo container-label sources, and that it should therefore be created exclusively for read-only public release-notes access.

Secondary issue (related, worth a doc note regardless)

Because the container-label check short-circuits before the OCI labels (index.ts:223-228), adding a dd.source.repo container label to an image that already carries a trusted org.opencontainers.image.source label silently downgrades the resolution from trusted to untrusted and drops the token. This is surprising and currently undocumented — at minimum it deserves a warning in the dd.source.repo docs ("don't set this as a container label if the image already exposes a trusted OCI source label").

Environment

• Version: 1.5.0

[scttbnsn]

@steilerDev this shipped in v1.5.1-rc.3. DD_RELEASE_NOTES_GITHUB_TOKEN is now forwarded to repos resolved from a dd.source.repo container label or a persisted container.sourceRepo, so you can pull release notes for third-party images without relying on the GHCR trust gate. The GHCR token fallback stays restricted to trusted sources (OCI image labels, GHCR image paths) and is never sent to a container-label source.

Since the dedicated token can be sent to a repo named by a (potentially attacker-controllable) container label, scope it narrowly: a classic PAT with public_repo only, or a fine-grained PAT with read-only Contents on public repos and nothing else. There's also a new warn line each watch cycle if a dd.source.repo label shadows a trusted OCI source label, so you'll see it if a label is downgrading a trusted source. Details are on the watchers config page.

rc.3 is a prerelease (ghcr.io/codeswhat/drydock:1.5.1-rc.3). Give it a spin and let me know if the scoping behaves the way you need before it goes GA.