Skip to main content

Adding an "Open in GitHub Codespaces" badge

You can add a badge to a Markdown file in your repository which people can click to create a codespace.

GitHub Codespaces is available for organizations using GitHub Team or GitHub Enterprise Cloud. GitHub Codespaces is also available as a limited beta release for individual users on GitHub Free and GitHub Pro plans. For more information, see "GitHub's products."

Overview

Adding an "Open in GitHub Codespaces" badge to a Markdown file gives people an easy way to create a codespace for your repository.

Screenshot of a Codespaces badge on a README page

When you create a badge you can choose specific configuration options for the codespace that the badge will create.

When people click the badge they'll be taken to the advanced options page for codespace creation, with the options you chose preselected. For more information about the advanced options page, see "Creating a codespace."

From the advanced options page, users can change the preselected settings if required, then click Create codespace.

Note: Be aware that people who don't yet have access to GitHub Codespaces will see a 404 message if they click this badge.

Creating an "Open in GitHub Codespaces" badge

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under the repository name, use the "Branch" drop-down menu, and select the branch you want to create the badge for.

    Screenshot of the Branch drop-down menu

  3. Click the Code button, then click the Codespaces tab.

    Screenshot of the New codespace button

  4. Click the down arrow at the side of the Create codespace on BRANCH button, click Configure and create codespace, then click the Configure and create codespace button.

    Screenshot of the "Configure and create codespace" option

  5. On the advanced options page for codespace creation, select the values you want to be preselected in each field.

    Screenshot of the advanced options page

  6. Copy the URL from the browser's address bar.

  7. Add the following Markdown to, for example, the README.md file of your repository:

    Markdown
    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](COPIED-URL)

    For example:

    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=0000000&machine=premiumLinux&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestUs2)
    

    In the above example, 0000000 will be the reference number of your repository. The other details in the URL are determined by the values you selected in the fields on the advanced options page.