skip to content

In a GitHub Codespaces devcontainer.json, which properties give new contributors the team's extensions, a big enough machine and a prompt for their API key?

level: middleimportance: should knowfreq 16%

answer

  1. a tool-specific namespace
  2. editor scope versus workspace scope
  3. a floor, not a machine choice
  4. asked for on the advanced page
  5. permissions beyond the own repository

basics

~10 s

customizations.vscode sets extensions and editor settings, hostRequirements hides machine types below a minimum, and a top-level secrets object prompts creators for recommended personal secrets; customizations.codespaces adds openFiles and extra repository permissions.

solid answer

~40 s

`customizations.vscode.extensions` lists extension IDs installed in the container when it is created, and `customizations.vscode.settings` applies default settings at the Remote [Codespaces] scope, which the repository's `.vscode/settings.json` (Workspace scope) overrides. `hostRequirements` with `cpus`, `memory` and `storage` limits creation to machine types that meet the minimum. A top-level `secrets` object names recommended secrets, each with an optional `description` and `documentationUrl`; people who have not created them are prompted on the advanced-options creation page, and entering a value is optional. Under `customizations.codespaces`, `openFiles` opens files the first time the codespace is opened in the VS Code web client, and `repositories` requests extra permissions on repositories with the same owner, which each creator must authorize. Keep the file to what everyone needs; themes and personal tools belong in each person's own settings.

code

json · 22 lines
json
{
  "image": "ghcr.io/acme/web-dev:2026-10",
  "hostRequirements": { "cpus": 4, "memory": "8gb" },
  "secrets": {
    "MAPS_API_KEY": {
      "description": "Your personal key for the maps service.",
      "documentationUrl": "https://example.com/docs/maps-key"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": ["github.vscode-pull-request-github"],
      "settings": { "editor.formatOnSave": true }
    },
    "codespaces": {
      "openFiles": ["README.md"],
      "repositories": {
        "acme/shared-config": { "permissions": { "contents": "read" } }
      }
    }
  }
}

go deeper

for a junior

Recall that extensions go under customizations.vscode, a minimum machine under hostRequirements, and personal API keys under secrets.

for a middle

Explain the settings scopes, when recommended secrets are prompted for, and why repository permissions need each creator's authorization.

for a senior

Spot the traps: permissions that skip existing codespaces, wildcards a prebuild rejects, and a machine floor that an organization policy leaves unsatisfiable.

for a principal

Decide what a shared configuration should enforce and what to leave to each developer, balancing a consistent onboarding experience against bloat and over-broad token permissions.

## Customization, not personalization A repository's `devcontainer.json` is shared by everyone who opens a codespace on it, so it should carry what **every** contributor needs: the linters, extensions, machine size and credentials prompts without which the project does not work. Personal preferences such as a colour theme or shell aliases belong in each person's own settings, which Codespaces applies separately. Within that rule, four groups of properties answer the usual onboarding complaints. ## Editor setup: customizations.vscode The `customizations` object holds tool-specific settings, one namespace per tool. VS Code's namespace has two properties: - `extensions`: an array of extension IDs, in `publisher.name` form, installed inside the container when it is created. - `settings`: default `settings.json` values written into a container-specific settings file. Settings in a codespace come from three scopes, and the most specific wins: | Scope | Source | Priority | |---|---|---| | Workspace | `.vscode/settings.json` in the repository | Highest | | Remote [Codespaces] | `customizations.vscode.settings` in `devcontainer.json` | Middle | | User | The person's own settings | Lowest | So a setting in `devcontainer.json` is a default that the repository's workspace settings can still override. ## Codespaces-only settings: customizations.codespaces Codespaces reads its own namespace from `devcontainer.json` (not from image metadata): - `openFiles`: an array of repository-relative paths opened the **first** time a codespace is opened in the **VS Code web client**; the first file is shown in the editor. It does nothing in the desktop application, and closed files are not reopened later. - `repositories`: extra permissions for the codespace's token on other repositories. Each entry names `owner/repository` with permissions such as `"contents": "read"` or `"issues": "write"`, or `"read-all"` / `"write-all"`. The permission rules are where people trip: 1. Only repositories with the **same owner** (personal account or organization) can be listed. 2. Each creator is **prompted to authorize** the permissions; Codespaces remembers the choice until the requested set changes, and a person can authorize only permissions they already hold. 3. Changes apply to codespaces created **after** the commit; an existing codespace does not gain them, even after a rebuild. 4. The `*` wildcard (`acme/*`) works for codespaces, but a configuration used by a prebuild must list each repository, and a prebuild can be granted only read access this way. ## A minimum machine: hostRequirements `hostRequirements` declares the smallest machine the project can use, with any of `cpus`, `memory` and `storage` (for example `"memory": "8gb"`). Creation then offers only machine types that meet or exceed it; smaller ones are marked as below the dev container's requirements. It is a floor, not a choice of machine: the creator still picks among qualifying types. An organization that restricts machine types can leave nothing that qualifies, so the minimum has to be set with that policy in mind. ## Recommended secrets Some secrets belong to the person, not the project: a personal API key for a third-party service, for example. A top-level `secrets` object lists their names, each with an optional `description` and `documentationUrl`. When someone creates a codespace through the advanced options page (**New with options**), each recommended secret appears as an input box if they have not created it, as a checkbox to associate an existing secret with the repository, or as a ticked box if it is already associated. Entering a value is optional, and nothing is created on anyone's behalf. Secrets the team shares are set at repository or organization level instead. The distinction is who can supply the value. A public project whose contributors must each bring their own key to a third-party service is the textbook case for a recommended secret: the repository cannot hold that key for them, but it can tell them, at the moment they create a codespace, exactly which secret is missing and where to read about it. A key the whole team shares, by contrast, is something the repository's owners can provide once. ## Putting it together | Complaint from a new contributor | Property | |---|---| | Missing the team's extensions | `customizations.vscode.extensions` | | Formatter not configured | `customizations.vscode.settings` (or `.vscode/settings.json`) | | Build runs out of memory on the default machine | `hostRequirements` | | App fails for lack of a personal API key | `secrets` | | Cannot read a sibling repository it needs | `customizations.codespaces.repositories` | | Does not know where to start | `customizations.codespaces.openFiles` |

  • Why might hostRequirements leave a contributor with no machine type to choose?
    An organization can restrict which machine types its members may use, usually to stop expensive choices. If the repository's minimum exceeds every allowed type, nothing qualifies and the contributor cannot create a suitable codespace, so the minimum must be set with the organization's policy in mind.
  • A devcontainer.json grants permissions on acme/* and works in codespaces, but the prebuild for it misbehaves. Why?
    The `*` wildcard is valid only for codespaces. A configuration used by a prebuild must list each repository, and this mechanism grants a prebuild read access to same-owner repositories only; write access or another owner's repositories need a `CODESPACES_PREBUILD_TOKEN` Codespaces repository secret holding a personal access token (classic).

  • Listing extensions in devcontainer.json is the place for each person's theme and keybindings
  • hostRequirements overrides the organization's machine-type restrictions
  • Recommended secrets are created automatically for every contributor
  • New repository permissions reach existing codespaces after a container rebuild
  • openFiles opens the files in every editor, including VS Code desktop