Understand how GitHub Codespaces works

GitHub Codespaces is a revolutionary, cloud-based development environment, instantly accessible and powered by containers. It comes pre-equipped with popular languages, tools, and utilities, streamlining your development process. What's more, GitHub Codespaces is highly customizable, allowing you to tailor a development environment specifically for your project's needs. This means you can establish a consistent, repeatable codespace configuration for everyone working on your project.

How to Create Your Codespace

There are several ways to initiate a codespace:

1. Start a new project using a GitHub template or any template repository on GitHub.com.
2. Begin work on a new feature from a branch in your repository.
3. Explore work-in-progress from an open pull request.
4. Investigate a bug by accessing a commit in a repository's history.

You can create a codespace directly on GitHub.com, in Visual Studio Code, or through the GitHub CLI.

Your codespace can be temporary for quick tests, or persistent for ongoing projects.

For detailed instructions, refer to "Creating a codespace for a repository," "Creating a codespace from a template," and "Opening an existing codespace."

Note: While you can create multiple codespaces per repository or branch, there are limits on the number and simultaneous running of codespaces. Exceeding these limits will prompt a message to remove an existing codespace before creating a new one.

The Codespace Creation Process

Creating a codespace involves several background steps:

1. VM and Storage Assignment: A virtual machine (VM) is allocated for your codespace, using either the stable or beta release of the VM host image. This VM, dedicated and private to you, runs on a specified version of Linux. A shallow clone of your repository (or template repository for template-based codespaces) is made into the VM's /workspaces directory and mounted into the development container.

2. Development Container Creation: GitHub Codespaces utilizes a Docker container as the development environment. This container is configured based on a devcontainer.json file and, optionally, a Dockerfile. Absence of a devcontainer.json file leads to the use of a default image with various languages and runtimes.

   Note: To use Git hooks in your codespace, set them up in the devcontainer.json file using postCreateCommand after the container is created.

3. Connecting to the Codespace: Once the container is ready and initializations are complete, you can connect to your codespace using a web browser, Visual Studio Code, a JetBrains IDE, or GitHub CLI.

4. Post-Creation Setup: Your codespace continues its setup based on the devcontainer.json configuration. This includes running postCreateCommand and postAttachCommand. For Git hooks, configure them using lifecycle scripts in devcontainer.json.

   If you have a public dotfiles repository for GitHub Codespaces, it can be integrated to personalize your codespace.

   For codespaces created from repositories, the entire repository history is cloned. For template-based codespaces, only the initial commit of the template repository is included, unless you start with a blank template.

Codespaces Lifecycle

• Saving Files: Save changes as usual, depending on your editor. In Visual Studio Code, enable Auto Save for constant synchronization.
• Closing or Stopping Your Codespace: Codespaces remain active during use but will time out after inactivity (default 30 minutes). You can define your personal timeout setting, subject to organizational policies. To stop a codespace, use the options provided in the browser, VS Code, JetBrains client, or GitHub CLI.
• Running Your Application: Port forwarding in codespaces allows access to TCP ports within your codespace. Ports are private by default but can be made accessible to your organization or publicly.
• Committing and Pushing Changes: Use Git as usual within your codespace. Commits will be attributed to your configured name and public email. GitHub Codespaces uses a token and your GitHub credentials for authentication.
• Personalizing Your Codespace: Customize your codespace with extensions or plugins in VS Code or JetBrains IDEs.

About the Directory Structure of a Codespace

Your repository is cloned into the persistent /workspaces directory in your codespace. Changes here are preserved across sessions and rebuilds. Outside /workspaces, changes are tied to the container's lifecycle, except for the /tmp directory.

To make robust changes across different codespaces:

• Use lifecycle command properties in your dev container configuration for installing programs and tools.
• Link GitHub Codespaces with a dotfiles repository for personal customizations.
• Use a devcontainer.json file to create symlinks for specific files to a persistent directory within /workspaces.

For more detailed information, refer to the respective sections in the GitHub documentation.