Create a GitHub Codespace with the Right Defaults

You will create a GitHub Codespace for a specific repository and branch, with explicit lifecycle settings, then confirm that GitHub created the environment you intended. The examples use GitHub CLI 2.87.3, installed on this machine. Allow about five minutes, plus the time needed for the codespace image to build.

You need the gh command, an authenticated GitHub account, access to the repository, and Codespaces availability for that account or organisation. This command creates a remote development environment. Treat the machine size, idle timeout and retention period as operational and cost decisions, not as harmless labels.

1. Check the command before creating anything

Read the installed help and confirm that the account is the one you mean to use:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh codespace create --help
Create a codespace

If you have not authenticated, use gh auth login and complete its prompts. Check the selected account with gh auth status. Do not copy a command from another terminal session until you have checked its repository owner and account.

Checkpoint: the help must show the --repo, --branch, --machine, --idle-timeout and --retention-period options. If it does not, stop and investigate the installed CLI rather than guessing at flags.

2. Create a codespace from a branch

Use the repository's full owner/name and an existing branch. Replace both placeholders before pressing Enter:

$ gh codespace create \
    --repo OWNER/REPOSITORY \
    --branch BRANCH_NAME \
    --display-name project-dev \
    --idle-timeout 30m \
    --retention-period 72h \
    --status

--repo identifies the repository and --branch selects its branch. The display name is limited to 48 characters. The idle timeout controls how long inactivity is allowed before the codespace is stopped. The retention period controls how long it may remain after stopping before automatic deletion, with a maximum of 30 days. --status asks the command to show the status of post-create commands and dotfiles.

There is no useful fixed output to paste into a runbook: the name and provisioning messages depend on the repository and GitHub account. Wait for the command to finish. If it returns an error, keep the complete error text and do not immediately repeat the command, because a partially completed request may already have created a resource.

This command normally needs no sudo. GitHub authentication and repository permissions are the relevant access checks; local root privileges do not grant either of them.

3. Verify the created resource

List your codespaces and filter by repository:

$ gh codespace list --repo OWNER/REPOSITORY
NAME                         DISPLAY NAME   REPOSITORY           BRANCH  STATE
example-quiet-otter-abc123   project-dev    OWNER/REPOSITORY     BRANCH  Available

Output columns vary with the CLI version and account data. The useful checks are the repository, branch, display name and state. If more than one row matches, use the unique name in the first column for the next command.

$ gh codespace view --codespace CODESPACE_NAME --json name,repository,state,machineName,idleTimeoutMinutes,retentionPeriodDays
{"name":"CODESPACE_NAME","repository":"OWNER/REPOSITORY","state":"Available","machineName":"basicLinux32gb","idleTimeoutMinutes":30,"retentionPeriodDays":3}

The JSON field names above are supported by the installed gh codespace view. The actual machine name and resource state will differ. If the output does not match your intended branch or limits, stop using the codespace and correct it through the appropriate Codespaces management command or GitHub interface. Do not create a second environment merely to compensate for an unverified first one.

4. Choose machine and location deliberately

Pass --machine when the repository needs a particular hardware specification:

$ gh codespace create \
    --repo OWNER/REPOSITORY \
    --branch BRANCH_NAME \
    --machine MACHINE_NAME \
    --location WestEurope \
    --display-name project-dev

The installed manual accepts a hardware specification through --machine. Its listed location values are EastUs, SouthEastAsia, WestEurope and WestUs2. If you omit --location, the location is determined automatically. Do not invent a machine name: obtain one offered for the repository and account, then pass it exactly.

Keep the first creation simple if you do not know the available machine types. A rejected location or machine is a provisioning failure, not a reason to add arbitrary spelling variations to the command.

5. Apply dev container and permission choices safely

If the repository contains more than one dev container configuration, select the intended file explicitly:

$ gh codespace create \
    --repo OWNER/REPOSITORY \
    --branch BRANCH_NAME \
    --devcontainer-path .devcontainer/devcontainer.json

The path is the path to the devcontainer.json file used for creation. Check that the file exists in the selected branch and review its lifecycle commands before starting a remote environment.

By default, the command can prompt when the codespace requests additional permissions. --default-permissions suppresses that prompt and accepts the additional permissions requested by the codespace. Use it only when the repository configuration and its maintainers are trusted, and when unattended creation is genuinely required. It is a security-sensitive convenience, not a general fix for a blocked prompt.

6. Know the browser shortcut and the undo path

--web creates the codespace from a browser. It cannot be combined with --display-name, --idle-timeout or --retention-period:

$ gh codespace create --repo OWNER/REPOSITORY --branch BRANCH_NAME --web

Use this mode when you want GitHub's browser flow to handle the remaining choices. Do not add the conflicting flags to the same command. If you created the wrong codespace, identify it with gh codespace list before deleting or stopping anything. Deletion is irreversible for the remote environment's uncommitted work, so preserve any needed changes first and use the Codespaces delete workflow only after checking the name.

For a normal correction, stop the codespace when you are finished and use the edit or management commands to change supported settings. The create command itself is not an edit operation and rerunning it creates another request.