skip to content

In GitHub Codespaces, how do Codespaces secrets differ from Actions secrets, and when does a codespace actually receive them?

level: middleimportance: should knowfreq 26%

answer

  1. two stores under one menu
  2. user, repository, organization
  3. environment variables at start, not build
  4. write access decides injection

basics

~20 s

Codespaces secrets are a separate store from Actions secrets, at user, repository and organization level. They become environment variables when a codespace is created or restarted, never during the image build, and only for users with write access.

solid answer

~50 s

GitHub Codespaces reads its own **development environment secrets**, created under *Secrets and variables > Codespaces* for a repository or organization, or in a user's personal Codespaces settings. The Actions store is a different set for workflows, so a value saved only there never reaches a codespace. Codespaces secrets are exported as environment variables into the codespace's terminal sessions when it is **created or restarted**; one added while a codespace runs appears only after a stop and start. They work in the terminal, SSH sessions and lifecycle scripts that run once the codespace is up, but **not** at build time (a Dockerfile, a custom entry point) or inside a dev container feature. They are not injected at all if the user lacks write access to the repository, and codespaces opened on a fork's pull request branch get none either. On a name clash the lower level wins: a repository secret beats an organization one.

go deeper

for a junior

Recall that Codespaces has its own secret store at user, repository and organization level, and that secrets show up as environment variables.

for a middle

Explain when secrets are injected (create or restart), where they cannot be used (build, features), the precedence rule and the write-access condition.

for a senior

Diagnose the empty-variable cases quickly and decide which credentials belong in Codespaces secrets given that every recipient can read them.

for a principal

Set the organization's rule for which credentials may live in development secrets and which stay outside developer environments altogether.

## Two stores that look alike GitHub keeps several secret stores side by side. Two matter here: | | **Actions secrets** | **Codespaces (development environment) secrets** | |---|---|---| | Consumed by | Workflow runs | Codespaces created for a repository (repository and organization ones also by its prebuilds) | | Where they are created | *Secrets and variables > Actions* | *Secrets and variables > Codespaces* (repository, organization) or the user's personal Codespaces settings | | Levels | Organization, repository, environment | **User**, **repository**, **organization** | | How they arrive | Passed into steps by the workflow | Exported as environment variables in the codespace | A token saved only as an Actions secret is invisible to a codespace. Teams that "already added the key to the repository secrets" and then find `$API_KEY` empty in their codespace have usually used the wrong store. ## The three levels - **User secrets** live in the developer's personal Codespaces settings. For each one, the owner chooses which repositories may receive it. They follow the person: most personal Codespaces settings, secrets included, apply whether the user or the organization owns the codespace. - **Repository secrets** need administrator access to the repository to create, and reach every codespace created for it by someone entitled to receive secrets. - **Organization secrets** need organization admin access and carry an access policy: all repositories, private repositories only, or a selected list. When the same name exists at more than one level, **the secret at the lower level takes precedence**: a repository secret named `API_KEY` beats an organization secret named `API_KEY`. Rules on names and size, as documented in October 2026: 1. letters, digits and underscores only, no spaces; 2. no `GITHUB_` prefix, and no leading digit; 3. names are not case-sensitive and must be unique at their level; 4. up to 100 secrets per user, per repository and per organization, each at most 48 KB. Values are encrypted with a libsodium sealed box before they reach GitHub and decrypted only when used in a codespace. ## When a codespace actually receives them Secrets are copied into the environment **when a codespace is created or restarted**. A secret created while a codespace is running is not visible in it until the codespace is stopped and started again. They can be used: - from the integrated terminal or an SSH session, for example to launch the application; - from dev container lifecycle scripts that run **after** the codespace is running. They cannot be used: - at **build time**, inside a Dockerfile or a custom entry point; - inside a **dev container feature**. A team that needs to pull images from a private registry other than GitHub's Container registry therefore creates the set of three secrets Codespaces looks for, named with a shared prefix and ending in `_CONTAINER_REGISTRY_SERVER`, `_CONTAINER_REGISTRY_USER` and `_CONTAINER_REGISTRY_PASSWORD`, rather than reading a secret inside the Dockerfile. ## Who receives them, and who does not - Secrets are **not copied** into a codespace if the user does not have write access to the codespace's repository. - Codespaces created from a pull request branch on a fork receive **none** of the user's Codespaces secrets. - Anyone who does receive a secret can read it in the terminal (`echo $SECRET_NAME` prints it). A repository-level Codespaces secret is therefore readable by every writer who opens a codespace there. That last point sets the boundary for an organization that wants to keep credentials out of its repositories: Codespaces secrets keep tokens out of committed files and `.env` files, but they do not hide a value from the developer using it. Development credentials belong here; production credentials do not. ## Diagnosing an empty variable When `$API_KEY` is empty in a codespace, walk the conditions in order: 1. Was it saved in the **Codespaces** store, not the Actions one? 2. For a user or organization secret, does its repository access include this repository? 3. Was it created **after** the codespace started? Stop and restart the codespace. 4. Does the user have **write access** to the repository, and is this codespace on the repository itself rather than a fork's pull request branch? 5. Is it being read at **build time**, in a Dockerfile or a feature, where secrets never arrive? Nearly every report of a missing secret is one of these five. ## Recommended secrets A repository's dev container configuration can list **recommended secrets**, which prompts a user who has not yet set them to supply values on the advanced creation page; the values land in that user's personal secrets. Writing that list belongs with the configuration file itself.

  • A developer adds a Codespaces secret while their codespace is open, but the variable is empty. Why?
    Codespaces secrets are copied into the environment when a codespace is created or restarted. A secret added while it runs is not injected into the existing session. Stopping and starting the codespace makes it available. It must also grant that repository access, if it is a user secret.
  • Why might a Dockerfile step that reads a Codespaces secret fail even though the secret exists?
    Codespaces secrets are available only after the codespace is built and running, as environment variables. They are not passed into the image build, a custom entry point or a dev container feature. Use them in a terminal or a lifecycle script that runs after start, or, to pull from another private registry, create the `_CONTAINER_REGISTRY_SERVER`, `_USER` and `_PASSWORD` secret set that Codespaces checks for.
  • Should a production database password be stored as an organization-level Codespaces secret?
    No. Every user with write access who opens a codespace in a repository the secret reaches gets it as an environment variable and can print it. Codespaces secrets keep credentials out of files, not out of developers' hands. Keep development credentials there and production ones elsewhere.

  • Codespaces reads the repository's Actions secrets, so one store serves both.
  • Codespaces secrets are available inside the Dockerfile while the image builds.
  • An organization secret overrides a repository secret with the same name.
  • A codespace opened on a fork's pull request branch still receives your secrets.
  • A Codespaces secret is masked and hidden from the developer using the codespace.