[Universe] - Codespaces Templates - combined work (#32149)
Co-authored-by: github-actions <github-actions@github.com> Co-authored-by: hubwriter <hubwriter@github.com> Co-authored-by: JP Ungaretti <19893438+jungaretti@users.noreply.github.com>
This commit is contained in:
Isaac Brown
@@ -20,7 +20,7 @@ Adding an "Open in {% data variables.product.prodname_github_codespaces %}" badg
|
||||
|
||||
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](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
|
||||
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 for a repository](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
|
||||
|
||||
From the advanced options page, users can change the preselected settings if required, then click **Create codespace**.
|
||||
|
||||
|
||||
@@ -19,5 +19,6 @@ children:
|
||||
- /adding-features-to-a-devcontainer-file
|
||||
- /automatically-opening-files-in-the-codespaces-for-a-repository
|
||||
- /adding-a-codespaces-badge
|
||||
- /setting-up-a-template-repository-for-github-codespaces
|
||||
---
|
||||
|
||||
|
||||
@@ -30,11 +30,13 @@ Alternatively, you can add your own custom configuration files. For more informa
|
||||
|
||||
You can define a single dev container configuration for a repository, different configurations for different branches, or multiple configurations. When multiple configurations are available, users can choose their preferred configuration when they create a codespace. This is particularly useful for large repositories that contain source code in different programming languages or for different projects. You can create a choice of configurations that allow different teams to work in a codespace that's set up appropriately for the work they are doing.
|
||||
|
||||
When you create a codespace from a template, you might start with one or more dev container configuration files in your workspace. To configure your environment further, you can add or remove settings from these files and rebuild the container to apply the changes to the codespace you're working in. If you publish your codespace to a repository on {% data variables.product.product_name %}, then any codespaces created from that repository will share the configuration you've defined. For more information, see "[Applying configuration changes to a codespace](#applying-configuration-changes-to-a-codespace)" and "[Creating a codespace from a template](/codespaces/developing-in-codespaces/creating-a-codespace-from-a-template#publishing-to-a-remote-repository)."
|
||||
|
||||
### devcontainer.json
|
||||
|
||||
The primary file in a dev container configuration is the `devcontainer.json` file. You can use this file to determine the environment of codespaces created for your repository. The contents of this file define a dev container that can include frameworks, tools, extensions, and port forwarding. The `devcontainer.json` file usually contains a reference to a Dockerfile, which is typically located alongside the `devcontainer.json` file.
|
||||
|
||||
If you don't add a `devcontainer.json` file to your repository, the default dev container configuration is used. For more information, see "[Using the default dev container configuration](#using-the-default-dev-container-configuration)."
|
||||
If you create a codespace from a repository without a `devcontainer.json` file, or if you start from {% data variables.product.company_short %}'s blank template, the default dev container configuration is used. For more information, see "[Using the default dev container configuration](#using-the-default-dev-container-configuration)."
|
||||
|
||||
The `devcontainer.json` file is usually located in the `.devcontainer` directory of your repository. Alternatively, you can locate it directly in the root of the repository, in which case the file name must begin with a period: `.devcontainer.json`.
|
||||
|
||||
@@ -44,7 +46,7 @@ If you want to have a choice of dev container configurations in your repository,
|
||||
|
||||
When you have multiple `devcontainer.json` files in your repository, each codespace is created from only one of the configurations. Settings cannot be imported or inherited between `devcontainer.json` files. If a `devcontainer.json` file in a custom subdirectory has dependent files, such as the Dockerfile or scripts that are run by commands in the `devcontainer.json` file, it's recommended that you co-locate these files in the same subdirectory.
|
||||
|
||||
For information about how to choose your preferred dev container configuration when you create a codespace, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
|
||||
For information about how to choose your preferred dev container configuration when you create a codespace, see "[Creating a codespace for a repository](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
|
||||
|
||||
{% data reusables.codespaces.more-info-devcontainer %}
|
||||
|
||||
@@ -154,11 +156,13 @@ If none of the predefined configurations meets your needs, you can create a cust
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: You can't locate your `devcontainer.json` files in directories more than one level below `.devcontainer`. For example, a file at `.devcontainer/teamA/devcontainer.json` will work, but `.devcontainer/teamA/testing/devcontainer.json` will not.
|
||||
**Notes**:
|
||||
- You can't locate your `devcontainer.json` files in directories more than one level below `.devcontainer`. For example, a file at `.devcontainer/teamA/devcontainer.json` will work, but `.devcontainer/teamA/testing/devcontainer.json` will not.
|
||||
- {% data reusables.codespaces.configuration-choice-templates %} For more information, see "[Setting up a template repository for {% data variables.product.prodname_github_codespaces %}](/codespaces/setting-up-your-project-for-codespaces/setting-up-a-template-repository-for-github-codespaces)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
If multiple `devcontainer.json` files are found in the repository, they are listed in the codespace creation options page. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
|
||||
If multiple `devcontainer.json` files are found in the repository, they are listed in the codespace creation options page. For more information, see "[Creating a codespace for a repository](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -14,10 +14,12 @@ topics:
|
||||
|
||||
## Overview
|
||||
|
||||
Each codespace that you create is hosted on a separate virtual machine, and you can usually choose from different types of virtual machines. Each machine type has different resources (processor cores, memory, storage) and, by default, the machine type with the least resources is used. For more information, see "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
|
||||
Each codespace that you create is hosted on a separate virtual machine. When you create a codespace from a repository, you can usually choose from different types of virtual machines. Each machine type has different resources (processor cores, memory, storage) and, by default, the machine type with the least resources is used. For more information, see "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
|
||||
|
||||
If your project needs a certain level of compute power, you can configure {% data variables.product.prodname_github_codespaces %} so that only machine types that meet these requirements can be used by default, or selected by users. You configure this in a `devcontainer.json` file.
|
||||
|
||||
{% data reusables.codespaces.machine-types-for-unpublished-codespaces %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Important:** Access to some machine types may be restricted at the organization level. Typically this is done to prevent people choosing higher resourced machines that are billed at a higher rate. If your repository is affected by an organization-level policy for machine types you should make sure you don't set a minimum specification that would leave no available machine types for people to choose. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)."
|
||||
@@ -39,7 +41,7 @@ If your project needs a certain level of compute power, you can configure {% dat
|
||||
|
||||
You can specify any or all of the options: `cpus`, `memory`, and `storage`.
|
||||
|
||||
To check the specifications of the {% data variables.product.prodname_github_codespaces %} machine types that are currently available for your repository, step through the process of creating a codespace until you see the choice of machine types. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
|
||||
To check the specifications of the {% data variables.product.prodname_github_codespaces %} machine types that are currently available for your repository, step through the process of creating a codespace until you see the choice of machine types. For more information, see "[Creating a codespace for a repository](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
|
||||
|
||||
1. Save the file and commit your changes to the required branch of the repository.
|
||||
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Setting up a template repository for GitHub Codespaces
|
||||
shortTitle: Set up a template repo
|
||||
intro: 'You can help people get started with a project by setting up a template repository for use with {% data variables.product.prodname_github_codespaces %}.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Codespaces
|
||||
- Set up
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
By setting up a template repository, you can help people get started with your framework, library, or other project in {% data variables.product.prodname_github_codespaces %}. Users will be able to start working with your template files immediately in a cloud-based development environment, without having to worry about cloning your repository or installing tools or other dependencies. With some configuration, you will be able to set users up in a codespace with important files already open for editing, and with an application already running in a preview browser tab within the {% data variables.product.prodname_vscode_shortname %} web editor.
|
||||
|
||||
Anyone with read access to your template repository can create a codespace from the repository's page on {% data variables.product.product_name %}. You can turn any existing repository into a template, and you do not have to change any settings to allow users to create a codespace from your template repository. For more information on turning a repository into a template, see "[Creating a template repository](/repositories/creating-and-managing-repositories/creating-a-template-repository)."
|
||||
|
||||
You can provide a link in the format `https://github.com/codespaces/new?template_repository=OWNER/TEMPLATE-REPO` to take users directly to a "Create a new codespace" page for your template.
|
||||
|
||||
|
||||
|
||||
For example, you could provide this link in a tutorial for getting started with your framework. In your link, replace `OWNER/TEMPLATE-REPO` with the name of your template repository, for example `monalisa/octo-template`.
|
||||
|
||||
When someone creates a codespace from your template, the contents of your template repository will be cloned into their codespace. When the user is ready, they will be able to publish their work to a new repository on {% data variables.product.product_name %} belonging to their personal account. Any usage charges for the codespace will be billed to the user who created it. For more information, see "[Creating a codespace from a template](/codespaces/developing-in-codespaces/creating-a-codespace-from-a-template)."
|
||||
|
||||
## Describe your template
|
||||
|
||||
If you don't have one, create a README for your template repository to describe the purpose of your template and how to get started with it. For more information, see "[About READMEs](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)."
|
||||
|
||||
A short description of your template is displayed on the "Create a new codespace" page that users land on when they follow the `https://github.com/codespaces/new?template_repository=OWNER/TEMPLATE-REPO` link. This description is taken from the **Description** field that you can set when you create a repository. You can edit this description at any time by navigating to the repository's page and clicking **{% octicon "gear" aria-label="The Settings gear" %}** next to the **About** section on the right of the page.
|
||||
|
||||
|
||||
|
||||
## Add starter files
|
||||
|
||||
Template repositories typically contain starter files with boilerplate code so users can quickly get started with a library, framework, or other technology.
|
||||
|
||||
For guidance on the kinds of files to include, you can look at the starter files included in the official {% data variables.product.company_short %} templates for {% data variables.product.prodname_github_codespaces %}, as follows.
|
||||
|
||||
{% data reusables.codespaces.your-codespaces-procedure-step %}
|
||||
{% data reusables.codespaces.view-all-templates-step %}
|
||||
1. To view the template repository that contains the files for the template, click the name of the template.
|
||||
|
||||
|
||||
|
||||
## Configure the container image
|
||||
|
||||
You can add dev container configuration files to your template repository to customize the development environment for people using your template with {% data variables.product.prodname_github_codespaces %}. You can choose from a list of predefined configuration settings in {% data variables.product.prodname_vscode %}, or you can create a custom configuration by writing your own `devcontainer.json` file. If you don't add configuration files, the default container image will be used. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)" and "[Add a dev container configuration to your repository](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces)."
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** {% data reusables.codespaces.configuration-choice-templates %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
You should configure your dev container with the tools and customization to give users the best experience with your template. For example, in your `devcontainer.json` file:
|
||||
- You can use the `openFiles` property to define a list of files to be opened automatically in the {% data variables.product.prodname_vscode_shortname %} web client when a codespace is created from your template.
|
||||
- If your template contains files for a web application, you can make the application run automatically in the user's codespace. You can do this by using the `postAttachCommand` property to run a script that starts the application on a local server as soon as the {% data variables.product.prodname_vscode_shortname %} web client connects to the codespace, and by setting the `onAutoForward` property of a port to `openPreview` to display the application running on that port in a simple browser embedded in the {% data variables.product.prodname_vscode_shortname %} web client.
|
||||
|
||||
The following configuration settings for a React template will open the `app.js` file in the user's editor, run `npm start` (defined in a `package.json` file) to start a local server, and forward port `3000` to a preview browser tab in the codespace.
|
||||
|
||||
```JSON
|
||||
{
|
||||
"postAttachCommand": {
|
||||
"server": "npm start",
|
||||
},
|
||||
|
||||
"portsAttributes": {
|
||||
"3000": {
|
||||
"label": "Application",
|
||||
"onAutoForward": "openPreview"
|
||||
}
|
||||
},
|
||||
|
||||
"customizations": {
|
||||
"codespaces": {
|
||||
"openFiles": ["src/App.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
For more information, see "[Automatically opening files in the codespaces for a repository](/codespaces/setting-up-your-project-for-codespaces/automatically-opening-files-in-the-codespaces-for-a-repository)" and the [dev containers specification](https://containers.dev/implementors/json_reference/#general-properties) on containers.dev.
|
||||
Reference in New Issue
Block a user