secrets and variables for codespaces and dependabot

[heurtematte]

As mentioned in the documentation: https://otterdog.readthedocs.io/en/latest/userguide/unsupported/, support for secrets and variables for Codespaces and Dependabot is currently missing.

This support is required for our project in particular, the Che project has an existing request to duplicate secrets for Dependabot: see https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/7038

While it is possible to handle this request manually as a temporary workaround, this approach does not scale and will become difficult to maintain if similar requests arise in the future.

[AlexanderLanin]

Before touching any code, this really warrants a discussion on the user-facing API.
Not about the internal implementation — that part is fairly obvious — but about what we want users to write and reason about.

I tried to keep my opinion separate.

---

Current situation

• GitHub has variables for:

  • Actions
  • Environments
    → Otterdog currently supports Actions variables only

• GitHub has secrets for:

  • Actions
  • Dependabot
  • Codespaces
  • Environments
    → Otterdog currently supports Actions secrets only

• The first draft for environment variables/secrets (feat: environment variables and secrets #549) is not merged yet, which makes this the perfect (and likely last) point to settle the user-facing API.

Despite being exposed as separate GitHub “features”, all of these share:

• identical CRUD semantics
• identical data models
• identical encryption approach for secrets
• nearly identical REST endpoints (prefix-only differences)

---

Conceptual model

Speaking generically, everything fits into: new<Scope><Feature><Artifact>

Where:

• Scope
  • Repo
  • Org
  • Environment
• Feature (repo + org only)
  • Actions
  • Dependabot
  • Codespaces
• Artifact
  • Secret
  • Variable

I’m intentionally not covering backwards compatibility mechanics here — that’s trivial and would just add noise.

---

Option A – Fully exploded types

The most trivial option is to multiply everything out, with scope, feature and artifact being part of the type name.

Repo

• newRepoActionsVariable
• newRepoActionsSecret
• newRepoDependabotSecret
• newRepoCodespacesSecret

Environment

• newEnvironmentVariable
• newEnvironmentSecret

Org

• newOrgActionsVariable
• newOrgActionsSecret
• newOrgDependabotSecret
• newOrgCodespacesSecret

IMHO: very explicit, but way too many functions, which add noise to documentation, implementation and jsonnet defaults without adding value.

---

Option B – Exploded types, scope inferred

As the scope is redundant information that can be inferred from the parent type, it can be dropped from the function name.

Repo & Org

• newActionsVariable
• newActionsSecret
• newDependabotSecret
• newCodespacesSecret

Environment

• newActionsVariable (or newVariable, not sure yet)
• newActionsSecret (or newSecret, not sure yet)

IMHO: good mix of explicitness and a manageable number of types. It drops redundant information like “add a repo secret to the repo” — well, where else would it go? It avoids confusion like "can I add a org secrets to my repo?". It’s also easy to explain: “you can add the same things on repo level and org level”.

---

Option C – Scope-specific types, feature as parameter

Another option is to forgo the feature in the type name and model it as a field.
Scope stays in the type name (repo / org / environment) and can also be inferred
from the parent element if desired. (So this builds a little closer on as-is..)

Variables

• newRepoVariable (Actions only)
• newOrgVariable (Actions only)
• newEnvironmentVariable (Actions only)

Secrets

• newRepoSecret { feature: "actions" | "dependabot" | "codespaces" }
• newOrgSecret { feature: "actions" | "dependabot" | "codespaces" }
• newEnvironmentSecret (Actions only)

IMHO: this hides the wrong information in the details: The redundant information is explicit, while the important information lives in the type details.

---

Option D – Minimal types

Push everything into parameters and keep the surface minimal.

• newVariable { scope: "repo" | "org" | "environment" }
• newSecret { scope: "repo" | "org" | "environment", feature: "actions" | "dependabot" | "codespaces" }

IMHO: as a software engineer I can fully get behind this solution,
but it may appear cryptic and less discoverable for users.

---

---

Caveat: org-level secrets need an access policy

One wrinkle: org-level secrets have additional access-policy attributes:

• visibility: all | private | selected
• selected_repositories: list of repos (only valid if visibility == "selected")

This makes Options B and D slightly more awkward, because these fields are only meaningful at org scope.

However, the same kind of conditionality already exists today:
selected_repositories is only valid when visibility == "selected".
So we already have validation rules like “field X is only allowed when condition Y is met” — this would just add another dimension (“only at org scope”).

---

IMHO

Personally, I strongly favor Option B. It removes information that is already implicit (the scope), while forcing users to be explicit about the things that actually matter: what kind of secret or variable this is. In practice, users already know whether they are operating at repo, org, or environment level based on where they place the object, so encoding that information again in the type name does not add clarity.

What Option B avoids particularly well is an explosion of near-identical constructors that differ only in subtle ways. From a user’s perspective, that kind of API tends to push complexity into the documentation, where people have to scan long reference tables and mentally diff type names to understand what they are allowed to use. I find it less confusing to have a small set of well-defined constructors with clear validation rules than a large number of superficially different ones.

Finally, while Option B does require certain fields to be valid only at certain levels (org-level access policies for secrets), that kind of conditional validation already exists today and is easy to explain (selected_repos may only exist when visibility is selected). In my experience, this is significantly easier for users to reason about than choosing between many similar-looking types whose differences only become apparent after reading the fine print.

[AlexanderLanin]

@netomi @kairoaraujo @lukpueh could you guys give some feedback here?

[lukpueh]

Thanks for the detailed discussion, @AlexanderLanin! I just gave this some thought and come to the same conclusion as you, that option B is favorable.

I find it hard to clearly draw the line between scope and feature. One could argue that all features are also just scopes, which may have a parent scope. I like that option B makes this distinction less important. The "leaf" scope (or feature) is explicit, and the (ancestor) scopes can be inferred.

@netomi, @kairoaraujo: Would this nested model fit with our jsonnet conventions?