Update guidance on creating service accounts for accessing private registries

[wbrefvem]

Summary
Documents that tokens are only issued to service accounts matching the naming pattern konflux-bot-[0-2] (e.g. konflux-bot-0, konflux-bot-1).

Changes

• Clarifies that any user with permission to create service accounts in a namespace can create a konflux-bot-[0-2] service account.
• Adds guidance on assigning konflux-*-bot-actions ClusterRoles, and links the two currently available roles (konflux-releaser-bot-actions and konflux-builder-bot-actions).
• Provides the oc create token command for minting tokens, and explains the required --duration flag (up to 1 year / 8760 hours), encouraging the shortest feasible duration.
• Notes the 3-service-account-per-namespace limit and that exceptions are handled case-by-case.
• Removes the now-inaccurate statement that tokens do not expire.

Motivation

The previous guidance was out of date: it stated that service account tokens do not expire and omitted the naming-pattern requirement, the ClusterRole assignments, and the token-duration constraints that users now need to follow.

EDIT: Number of allowed SAs per namespace has been reduced to 3

[qodo-app-for-konflux-ci]

PR Summary by Qodo

Document service account requirements for private registry access

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Documents required konflux-bot-[0-9] naming and namespace service-account permissions.
• Links available bot ClusterRoles and explains scoped role assignment.
• Replaces non-expiring-token guidance with bounded token durations and namespace limits.

Diagram

graph TD
  U["Authorized user"] --> SA["Named service account"] --> RBAC["Bot ClusterRole"]
  SA --> CLI["oc token command"] --> TOK["Expiring token"] --> ACCESS["Registry and API"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Update the complete service-account procedure

• ➕ Eliminates conflicting legacy account names and secret-based token instructions later on the page
• ➕ Gives users one executable workflow matching the new constraints
• ➖ Expands the change beyond the token-type summary
• ➖ Requires validating replacement commands and examples

Recommendation: Extend this approach to the page's detailed service-account procedure. The current summary correctly introduces konflux-bot-[0-9] and oc create token, but the later example still uses external-puller and a legacy service-account-token Secret, which can direct readers away from the newly documented requirements.

Files changed (1) +7 / -2

Documentation (1) +7 / -2

accessing-private-images.adocClarify bot account and token requirements +7/-2

Clarify bot account and token requirements

• Documents the required bot service-account naming pattern, eligible creators, and available action ClusterRoles. Adds the token-minting command, maximum duration, shortest-duration recommendation, and namespace account limit while removing the claim that tokens never expire.

modules/building/pages/accessing-private-images.adoc

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[qodo-app-for-konflux-ci]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Walkthrough uses disallowed account ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new naming restriction only permits tokens for konflux-bot-[0-9], but the page's
external-system walkthrough still creates external-puller and requests its token. Following the
documented steps therefore cannot produce a token under the policy this change introduces.

Code

modules/building/pages/accessing-private-images.adoc[58]

+** Tokens are only issued to service accounts named according to the pattern `konflux-bot-[0-9]` (e.g. `konflux-bot-0`, `konflux-bot-1`, etc)

Relevance

●●● Strong

Accepted precedents favor correcting documentation examples that omit required fields or contradict
authentication guidance.

PR-#554
PR-#615

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added restriction at line 58 allows token issuance only for konflux-bot-[0-9], while the same
page creates external-puller, associates the token Secret with that account, and uses it for
login.

modules/building/pages/accessing-private-images.adoc[58-58]
modules/building/pages/accessing-private-images.adoc[94-116]
modules/building/pages/accessing-private-images.adoc[119-131]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The external-system walkthrough creates `external-puller`, although tokens are now only issued for service accounts matching `konflux-bot-[0-9]`.

## Issue Context
Use one consistent allowed service-account name throughout the YAML, token command, and registry-login examples.

## Fix Focus Areas
- modules/building/pages/accessing-private-images.adoc[94-130]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Walkthrough bypasses token duration ✓ Resolved 🐞 Bug ⛨ Security

Description

The new guidance says --duration is mandatory, but the executable walkthrough still creates a
kubernetes.io/service-account-token Secret and reads its token without specifying any duration.
Users following the detailed procedure bypass the newly documented expiring-token workflow and
receive contradictory guidance on how tokens must be minted.

Code

modules/building/pages/accessing-private-images.adoc[R62-63]

+** Tokens can be minted with `oc create token konflux-bot-<bot-number> -n <your-namespace> --duration=8760h`
+** `--duration` must be specified and can be any value up to 1 year (8760 hours). Users are encouraged to specify the shortest feasible duration

Relevance

●●● Strong

The executable Secret-based walkthrough directly contradicts the PR’s mandatory expiring-token
workflow; documentation consistency fixes are accepted.

PR-#554
PR-#615

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Lines 62-63 require token minting with an explicit duration, but lines 105-123 instead create a
token Secret whose manifest contains no duration and extract that token directly; line 141 continues
to describe Secret deletion as the token lifecycle mechanism.

modules/building/pages/accessing-private-images.adoc[62-63]
modules/building/pages/accessing-private-images.adoc[105-123]
modules/building/pages/accessing-private-images.adoc[141-141]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The detailed external-system procedure still creates and reads a service-account token Secret, contradicting the new requirement to mint tokens with an explicit `--duration`.

## Issue Context
Replace the Secret manifest and extraction command with the documented `oc create token` flow, and update the revocation/renewal note for expiring tokens.

## Fix Focus Areas
- modules/building/pages/accessing-private-images.adoc[105-123]
- modules/building/pages/accessing-private-images.adoc[141-141]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app

[oswcab]

/lgtm

[github-actions]

🚀 Preview is available at: https://pr-648--konflux-docs.netlify.app