Skip to content

SCOPE.md

Latest commit

 

History

History
80 lines (59 loc) · 5.47 KB

SCOPE.md

File metadata and controls

80 lines (59 loc) · 5.47 KB
Raw

SCOPE — terraform-github-codespaces

GitHub Codespaces secrets at repository, organization, and user scope — the direct mirror of terraform-github-dependabot, one scope up to include the user-level secret.

In-scope resources

Resource Role
github_codespaces_secret.repo for_each map of repository-scoped Codespaces secrets (sensitive).
github_codespaces_organization_secret.org for_each map of organization-scoped Codespaces secrets with visibility (all / private / selected).
github_codespaces_organization_secret_repositories.allow Selected-repository allow-lists for selected-visibility org secrets.
github_codespaces_user_secret.user for_each map of user-scoped Codespaces secrets (sensitive).

There is no single dominant resource — this is a scope-spanning secrets bundle. Name each collection by role (repo, org, allow, user); no this. (Same shape as terraform-github-dependabot.)

Out-of-scope resources (consumed by reference, never created here)

  • github_repository — consumed by name (repo secrets) / numeric id (org selected allow-lists) from terraform-github-repository.
  • github_actions_secret / github_dependabot_secret — different feature, owned by terraform-github-actions-repository / terraform-github-dependabot.

Consumes

Input Type Source module
repository_secrets[].repository string (repo name) terraform-github-repository (id output)
organization_secrets[].selected_repository_ids list(number) terraform-github-repository (repo_id output)
secret_repository_access[].selected_repository_ids list(number) terraform-github-repository (repo_id output)
user_secrets[].selected_repository_ids list(number) terraform-github-repository (repo_id output)

Emits

Output Description Consumed by
repository_secret_names Set of managed repo Codespaces secret names (values never emitted) Audit / drift detection
repository_secret_ids Map: name → <repo>:<secret> resource id Reporting
organization_secret_names Set of managed org Codespaces secret names Audit
organization_secret_ids Map: name → resource id Reporting
user_secret_names Set of managed user Codespaces secret names Audit
user_secret_ids Map: name → resource id Reporting
secret_repository_access_ids Map: secret name → allow-list resource id Reporting

🔒 No secret values are ever output. Only names and resource ids are emitted.

Required token scopes / GitHub App permissions

Classic PAT scopes

  • repo — repository Codespaces secrets
  • admin:org — organization Codespaces secrets and allow-lists
  • codespace:secrets (user) — user-scoped Codespaces secrets

Fine-grained PAT / GitHub App permissions

  • Repository permissions → Codespaces secrets: read/write
  • Organization permissions → Codespaces secrets / Organization Codespaces secrets: read/write
  • User permissions → Codespaces user secrets: read/write (for the user-scoped resource)
  • Metadata: read

⚠️ Auth and the target org (owner / GITHUB_OWNER) are provider concerns — never module variables.

GitHub Prerequisites

  • Codespaces must be enabled for the organization (and billing configured) before org/repo Codespaces secrets can be created.
  • Plan / edition: org-level Codespaces secrets require GitHub Team or Enterprise Cloud; user secrets work for any user with Codespaces access. Confirm the org's Codespaces policy permits the targeted repos.
  • selected-visibility org secrets require selected_repository_ids (the repo numeric ids — wire from terraform-github-repository.repo_id).
  • Rate limit: each secret is one API write plus a public-key fetch for encryption — watch secondary rate limits on large for_each maps.
  • ⚠️ Many regulated orgs disable Codespaces entirely — confirm Codespaces is part of the Casey's GitHub footprint before adopting this module.

Provider gotchas

  • Secret plaintext_value is sensitive = true; prefer encrypted_value pre-encrypted with the appropriate Codespaces public key. ⚠️ These resources expose no key_id argument (confirmed against integrations/github 6.12.1) — unlike some other secret APIs, the provider resolves the public key internally, so supply only the Base64 encrypted_value. var.*_secrets maps are sensitive, so main.tf iterates nonsensitive(keys(...)) to satisfy Terraform's for_each-over-sensitive restriction (same pattern as terraform-github-repository-environment / terraform-github-dependabot).
  • Org secret visibility is all / private / selected; selected pairs with the allow-list resource — own the allow-list in exactly one place (don't also set selected_repository_ids inline on the secret).
  • Secret/variable names are stored; values are write-only — the provider cannot detect remote-value drift.
  • No tags, no timeouts.

Design decisions

  • Boundary = all Codespaces secret scopes behind one module, mirroring terraform-github-dependabot (repo + org + allow-list) and adding the user scope. Keeping secrets-by-feature consistent across Dependabot / Actions / Codespaces makes the library predictable.
  • Aggregation shape (no this) — each scope is an independent role-named for_each collection defaulting to {}, so a caller enables only the scopes they use.