Skip to main content

Restricting the base image for codespaces

You can specify which base images can be used for new codespaces created within your organization.

Who can use this feature

To manage image constraints for an organization's codespaces, you must be an owner of the organization.

Overview

When you create a codespace, a Docker container is automatically created on a remote virtual machine. The Docker container is created from a Docker image. The image is effectively a template for Docker containers and it determines many aspects of the resulting environment provided by the codespace.

You can choose which image you want to use for your codespaces by specifying it in the dev container configuration for a repository. You can do this, for example, by using the image property in the devcontainer.json file.

JSON
"image": "mcr.microsoft.com/vscode/devcontainers/javascript-node:18",

For more information, see the dev containers specification on containers.dev.

If you don't specify an image in the dev container configuration for a repository, the default image is used. The default image contains a number of runtime versions for popular languages and commonly used tools. For more information, see "Introduction to dev containers."

As an organization owner, you can add a policy to restrict which images can be used for codespaces created within your organization.

If the image specified in the dev container configuration does not match one of the allowed images, the following message is displayed when someone tries to create a codespace for the repository:

Codespace could not be created: Base image 'DETAILS FROM DEV CONTAINER CONFIGURATION' is not allowed based on an organization policy set by your organization administrator.

Notes:

  • The base image policy is only applied when a codespace is created. It is currently not applied when you rebuild a container. This will change in a future release. For more information, see "The codespace lifecycle."
  • The base image policy does not apply to the default image, or the image that's used to recover a codespace if an error is introduced into a dev container configuration which prevents the container from being rebuilt.

Setting organization-wide and repository-specific policies

When you create a policy you choose whether it applies to all repositories in your organization, or only to specified repositories. If you set an organization-wide policy then any policies you set for individual repositories must fall within the restriction set at the organization level. Adding policies makes the choice of image more, not less, restrictive.

For example, you could create an organization-wide policy that restricts the base image to any of ten specified images. You can then set a policy for Repository A that restricts the image to a subset of just two of the images specified at the organization level. Specifying additional images for Repository A will have no effect because these images are not specified in the organization-level policy. If you add an organization-wide policy, you should set it to the largest choice of images that will be available for any repository in your organization. You can then add repository-specific policies to further restrict the choice.

Note: Codespace policies only apply to codespaces for which your organization will be billed. If an individual user creates a codespace for a repository in your organization, and the organization is not billed, then the codespace will not be bound by these policies. For information on how to choose who can create codespaces that are billed to your organization, see "Enabling GitHub Codespaces for your organization."

Adding a policy to define the allowed images

  1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations. Your organizations in the profile menu

  2. Next to the organization, click Settings. The settings button

  3. In the "Code, planning, and automation" section of the sidebar, select Codespaces then click Policies.

  4. On the "Codespace policies" page, click Create Policy.

  5. Enter a name for your new policy.

  6. Click Add constraint and choose Base images.

    Screenshot of the 'Add constraint' dropdown menu

  7. Click to edit the constraint.

    Screenshot of the pencil icon for editing the constraint

  8. In the "Allowed values" field, enter the complete URL of an image you want to allow.

    Screenshot of an entry in the 'Allowed values' field

    Note: You must specify an image URL that exactly matches the value specified in a dev container configuration.

  9. Click the plus button () to add the value.

  10. If required, repeat the previous two steps to add more image URLs.

  11. Click outside of the dialog box to close it.

  12. By default the policy is set to apply to all repositories, if you want it to apply only to some of the repositories in your organization, click All repositories and then click Selected repositories in the dropdown menu.

    Screenshot of choosing 'Selected repositories'

    With Selected repositories selected:

    1. Click .

      Screenshot of the gear icon for editing the settings

    2. Select the repositories you want this policy to apply to.

    3. At the bottom of the repository list, click Select repositories.

      Screenshot of selected repositories for this policy

  13. If you want to add another constraint to the policy, click Add constraint and choose another constraint. For information about other constraints, see:

  14. After you've finished adding constraints to your policy, click Save.

The policy is applied when anyone attempts to create a new codespace that is billable to your organization. The base image constraint does not affect existing codespaces, either active or stopped.

Editing a policy

You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy.

  1. Display the "Codespace policies" page. For more information, see "Adding a policy to define the allowed images."
  2. Click the name of the policy you want to edit.
  3. Click the pencil icon () beside the "Base images" constraint.
  4. Add or remove image URLs.
  5. Click Save.

Deleting a policy

  1. Display the "Codespace policies" page. For more information, see "Adding a policy to define the allowed images."

  2. Click the delete button to the right of the policy you want to delete.

    Screenshot of the delete button for a policy