chore(adr): apl-addons ArgoCD project for platform-admin addon deployments

[j-zimnowoda]

📌 Summary

#3428

🔍 Reviewer Notes

🧹 Checklist

• Code is readable, maintainable, and robust.
• Unit tests added/updated

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (2)

CONTEXT.md:33

• CreateNamespace is not a boolean field on the ArgoCD Application; the operator sets it via the syncOptions entry CreateNamespace=true. The current wording (CreateNamespace: true) suggests a YAML key that doesn’t exist in the Application spec and can mislead readers.

**gitops-ns Application**: An ArgoCD Application named `gitops-ns-{namespace}` created by the apl-operator for each namespace directory. Syncs all manifests in that directory into the corresponding namespace with `prune: true` and `CreateNamespace: true`.

adr/2026-07-07-apl-addons-argocd-project.md:11

• This ADR describes the apl-addons AppProject/namespace as already introduced, but this PR only adds documentation (the only apl-addons references are in these ADR/context files). Consider switching to future tense (or adding the implementation changes in the same PR) so the ADR doesn’t read like the feature already exists in code.

A new `apl-addons` AppProject and namespace are introduced. Platform admins drop ArgoCD `Application` CRs into `env/manifests/namespaces/apl-addons/` in the values repo. The existing `addGitOpsApps` mechanism (which scans `env/manifests/namespaces/*` and creates one `gitops-ns-{namespace}` ArgoCD Application per directory) picks this up automatically and syncs those Application CRs into the `apl-addons` namespace. ArgoCD's "app in any namespace" feature then reconciles them under the `apl-addons` project.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (5)

CONTEXT.md:36

• This App-of-Apps definition references a concrete gitops-ns-apl-addons Application as if it already exists. If this PR is only recording the ADR, consider wording this conditionally (e.g., "when implemented") so the glossary remains accurate for current releases.

**App-of-Apps**: The pattern where one ArgoCD Application manages a directory of other Application CRs. The `gitops-ns-apl-addons` Application is an App-of-Apps: it syncs Application CRs into the `apl-addons` namespace, where ArgoCD picks them up via the "app in any namespace" feature.

CONTEXT.md:31

• This definition implies the apl-addons AppProject already exists and is active. Since this PR is documentation-only, consider making this explicitly a planned/defined project (or referencing the ADR) to prevent readers from assuming the cluster will already contain an apl-addons AppProject after upgrading.

**apl-addons project**: The AppProject named `apl-addons` that governs Applications dropped by platform admins. Fully unrestricted: any source repo, any destination namespace, any cluster, any resource type.

CONTEXT.md:22

• This glossary entry states that apl-addons/ is the "only current example", but this PR only adds documentation and the repository currently has no apl-addons manifests directory or related wiring. Consider wording this as a defined/planned concept (and/or link to the ADR) to avoid implying the feature already exists.

This issue also appears in the following locations of the same file:

• line 31
• line 36

**Platform-admin-owned directory**: A namespace directory whose name starts with `apl-` and whose contents are written by human platform admins, not the apl-operator program. `apl-addons/` is the only current example. The operator bootstraps the directory but does not manage its contents.

adr/2026-07-07-apl-addons-argocd-project.md:37

• In an ArgoCD Application, the project is set via spec.project, not project at the top level. Using the wrong field name here could mislead operators copying from the ADR.

ArgoCD AppProject `destinations` is a whitelist only — there is no native destination blacklist. Platform admins must not target the `argocd` namespace as a destination; this is documented but not enforced. Application CRs must set `project: apl-addons`; if they do not, ArgoCD will reject them with an RBAC error (no operator-level pre-validation is added).

adr/2026-07-07-apl-addons-argocd-project.md:17

• sourceRepos governs Git/Helm/OCI artifact sources ArgoCD can fetch, but the current wording could be read as allowing container image registries (which AppProjects don't control). Suggest clarifying that this is about Git repos and Helm repositories/OCI registries.

- `sourceRepos: ['*']` — platform admins must be free to pull from any registry or git host

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (4)

CONTEXT.md:31

• This defines the apl-addons AppProject as if it already exists, but there are no corresponding ArgoCD values/templates in this PR (and no other repo references). Consider wording this as a planned project until the implementation lands (or include the implementation in this PR).

**apl-addons project**: The AppProject named `apl-addons` that governs Applications dropped by platform admins. Fully unrestricted: any source repo, any destination namespace, any cluster, any resource type.

CONTEXT.md:36

• This references a gitops-ns-apl-addons Application, but there is currently no apl-addons namespace directory/bootstrap in the codebase. If this is aspirational documentation, please qualify it as such; otherwise it reads like behavior that exists today.

**App-of-Apps**: The pattern where one ArgoCD Application manages a directory of other Application CRs. The `gitops-ns-apl-addons` Application is an App-of-Apps: it syncs Application CRs into the `apl-addons` namespace, where ArgoCD picks them up via the "app in any namespace" feature.

adr/2026-07-07-apl-addons-argocd-project.md:11

• This ADR states that the apl-addons AppProject/namespace "are introduced" and that addGitOpsApps will pick up env/manifests/namespaces/apl-addons/, but there are no corresponding code/template changes in this PR (repo-wide search shows no non-doc references to apl-addons). If this PR is ADR-only, the text should be future/conditional; otherwise the implementation changes (utils bootstrap dir + argocd templates/AppProject/VAP) are missing.

A new `apl-addons` AppProject and namespace are introduced. Platform admins drop ArgoCD `Application` CRs into `env/manifests/namespaces/apl-addons/` in the values repo. The existing `addGitOpsApps` mechanism (which scans `env/manifests/namespaces/*` and creates one `gitops-ns-{namespace}` ArgoCD Application per directory) picks this up automatically and syncs those Application CRs into the `apl-addons` namespace. ArgoCD's "app in any namespace" feature then reconciles them under the `apl-addons` project.

CONTEXT.md:22

• apl-addons/ is described as an existing platform-admin-owned directory, but there are currently no non-doc references to apl-addons in the repo. If this file is meant to document current behavior, this should be phrased as planned/future, or the implementation changes should be included in the PR.

This issue also appears in the following locations of the same file:

• line 31
• line 36

**Platform-admin-owned directory**: A namespace directory whose name starts with `apl-` and whose contents are written by human platform admins, not the apl-operator program. `apl-addons/` is the only current example. The operator bootstraps the directory but does not manage its contents.