Codespaces: recommended secrets / one-click experience (#35684)

Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
Co-authored-by: isaacmbrown <isaacmbrown@github.com>

content/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository.md

@@ -82,9 +82,9 @@ If you want to use Git hooks for your codespace, then you should set up hooks us
 
    * **Use the default options**
 
-      To create a codespace using the default options, click the plus sign ({% octicon "plus" aria-label="The plus icon" %}). Alternatively, if you don't currently have any codespaces for this repository, you can click **Create codespace on BRANCH**.
+      To create a codespace using the default options, click the plus sign ({% octicon "plus" aria-label="The plus icon" %}). Alternatively, if you don't currently have any codespaces for this repository, you can click **Create codespace on BRANCH**. <br/><br/>
 
-   * **Configure options**
+   * **Configure advanced options**
 
       To configure advanced options for your codespace, such as a different machine type or a particular `devcontainer.json` file:
 
@@ -96,13 +96,15 @@ If you want to use Git hooks for your codespace, then you should set up hooks us
 
          ![Screenshot of the advanced options page with buttons for "Branch," "Dev container configuration," "Region," and "Machine type."](/assets/images/help/codespaces/advanced-options.png)
 
+         The options page may also display the names of one or more secrets that it's recommended you create in your {% data variables.product.prodname_codespaces %} settings. For more information, see "[Recommended secrets](#recommended-secrets)."
+
          {% note %}
 
          **Notes**
 
          * You can bookmark the options page to give you a quick way to create a codespace for this repository and branch.
          * The [https://github.com/codespaces/new](https://github.com/codespaces/new) page provides a quick way to create a codespace for any repository and branch. You can get to this page quickly by typing `codespace.new` into your browser's address bar.
-         * For more information about the `devcontainer.json` file, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#devcontainerjson)."
+         * For more information about dev container configuration files, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)."
          * For more information about machine types, see "[AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
          * {% data reusables.codespaces.codespaces-machine-type-availability %}
 
@@ -110,6 +112,20 @@ If you want to use Git hooks for your codespace, then you should set up hooks us
 
       1. Click **Create codespace**.
 
+## Recommended secrets
+
+The names of user-defined secrets may be displayed on the advanced options page when you create a codespace. This will happen if recommended secrets have been specified in the dev container configuration you have selected. 
+         
+<img src="/assets/images/help/codespaces/recommended-secrets.png" style="max-height:50rem"  alt='Screenshot of the "Create codespace" page with four recommended secrets highlighted with a dark orange outline.' />
+
+Entering values for these secrets, when you're prompted to do so, is recommended because it's likely your project will need values for these secrets. However, supplying values is not required for you to create a codespace. You can set these secrets within the codespace if you prefer.
+
+If you enter a value for a recommended secret, the secret will available in the new codespace. When you click **Create codespace**, the secret is also added to your personal settings for {% data variables.product.prodname_codespaces %}, so you will not need to enter a value for the secret in future when you create a codespace for this repository.
+         
+If the name of a secret is shown with a checkbox that is unavailable for selection, and no input box, this is because you already have a secret of this name configured in your personal settings for {% data variables.product.prodname_codespaces %}, and you have associated it with this repository. If you've created a secret of this name but have not associated it with this repository, the checkbox will be available to select and by doing so you can update your settings to add the association.
+         
+If you want to change the value of a preselected secret you can do so from your personal settings for {% data variables.product.prodname_codespaces %} at [github.com/settings/codespaces](https://github.com/settings/codespaces). For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
+
 {% endwebui %}
 
 {% vscode %}
@@ -148,4 +164,4 @@ For full details of the options for this command, see [the {% data variables.pro
 
 ## Further reading
 - "[AUTOTITLE](/codespaces/developing-in-codespaces/opening-an-existing-codespace)"
-- "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge)"
+- "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces)"

content/codespaces/developing-in-codespaces/opening-an-existing-codespace.md

@@ -28,10 +28,32 @@ You can view all your codespaces on the "Your codespaces" page at [github.com/co
 - Create a new codespace, either by choosing one of {% data variables.product.company_short %}'s templates or by clicking **New codespace**. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-from-a-template)" and "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository)."
 - Prevent automatic deletion of a codespace. For more information, see "[AUTOTITLE](/codespaces/customizing-your-codespace/configuring-automatic-deletion-of-your-codespaces?tool=webui#avoiding-automatic-deletion-of-codespaces)."
 
-## Reopening a codespace
-
 {% webui %}
 
+## Resuming a codespace from a repository page
+
+You can quickly resume a codespace when you're viewing a repository on {% data variables.product.prodname_dotcom_the_website %}.
+
+1. With the repository displayed on {% data variables.product.prodname_dotcom_the_website %}, press <kbd>,</kbd>.
+
+   The "Resume codespace" page is displayed. This allows you to resume your most recently used codespace for the currently selected branch of the repository or, if you were viewing a pull request, for the topic branch of the pull request.
+
+   ![Screenshot of the "Resume codespace" page showing the "Resume this codespace" and "Create a new one" buttons.](/assets/images/help/codespaces/resume-codespace.png)
+
+1. Click **Resume this codespace**.
+
+   Alternatively, if you want to create a new codespace for this branch of the repository, click **Create a new one**.
+
+   {% note %}
+
+   **Note**: If you don't have an existing codespace for this branch, the page is titled "Create codespace" and a button labeled **Create a new codespace** is displayed.
+
+   {% endnote %}
+
+You can bookmark the address of this page if you want to get back to it quickly to resume your codespace. Alternatively you can use the address in a link to provide other people with a quick way of creating and resuming their own codespaces for this repository.
+
+## Opening an existing codespace from the "Your codespaces" page
+
 {% data reusables.codespaces.your-codespaces-procedure-step %}
 1. To open a codespace in your default editor, click the name of the codespace. {% data reusables.codespaces.about-changing-default-editor %} For more information, see "[AUTOTITLE](/codespaces/customizing-your-codespace/setting-your-default-editor-for-github-codespaces)."
 
@@ -57,6 +79,8 @@ You can view all your codespaces on the "Your codespaces" page at [github.com/co
 
 {% vscode %}
 
+## Reopening an existing codespace
+
 {% note %}
 
 **Note:** {% data reusables.codespaces.using-codespaces-in-vscode %} For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-in-visual-studio-code)."
@@ -80,6 +104,8 @@ You can also access the commands listed above by navigating to the Remote Explor
 
 {% cli %}
 
+## Reopening an existing codespace
+
 1. In a terminal, enter one of the following {% data variables.product.prodname_cli %} commands.
    - To open a codespace in {% data variables.product.prodname_vscode_shortname %}, enter:
 
@@ -126,6 +152,8 @@ For more information, see [`gh codespace code`](https://cli.github.com/manual/gh
 
 {% jetbrains %}
 
+## Reopening an existing codespace
+
 {% data reusables.codespaces.opening-codespace-in-jetbrains %}
 
 {% endjetbrains %}

content/codespaces/guides.md

@@ -18,7 +18,8 @@ includeGuides:
   - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/setting-a-minimum-specification-for-codespace-machines
   - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file
   - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository
-  - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge
+  - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository
+  - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces
   - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces
   - /codespaces/customizing-your-codespace/personalizing-github-codespaces-for-your-account
   - /codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository

content/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces.md

@@ -17,7 +17,9 @@ product: 'Encrypted secrets are available in all public repositories, in private
 
 ## About secrets
 
-Secrets are encrypted environment variables that you create in an organization or  repository. The secrets that you create are available to use in {% data variables.product.prodname_github_codespaces %}. GitHub uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) to encrypt secrets before they reach GitHub and only decrypts them when you use them in a codespace.
+Secrets are encrypted environment variables that you create in the {% data variables.product.prodname_github_codespaces %} settings for an organization, a repository, or a personal account. For information on creating user-specific secrets, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
+
+The secrets that you create are available to use in {% data variables.product.prodname_github_codespaces %}. {% data variables.product.prodname_dotcom %} uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) to encrypt secrets before they reach {% data variables.product.prodname_dotcom %} and only decrypts them when you use them in a codespace.
 
 Organization-level secrets let you share secrets between multiple repositories, which reduces the need to create duplicate secrets. You can use access policies to control which repositories can use organization secrets.
 
@@ -35,6 +37,10 @@ You can store up to 100 secrets per organization and 100 secrets per repository.
 
 Secrets are limited to 48 KB in size.
 
+### Recommended secrets for a repository
+
+Your project may require specific user secrets. For example, to run the application in a codespace, the user may need to supply a personal API key. If this is the case, you can specify recommended secrets in the dev container configuration. The user will then be prompted to supply values for these secrets, if they haven't already created these personal secrets, when they use the advanced options page to create a codespace. If the user supplies a secret value for use in the codespace, this secret is added to their personal settings for {% data variables.product.prodname_codespaces %}. They will not have to enter a value for this secret when they create a codespace for this repository in future. For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository)." 
+
 ## Adding secrets for a repository
 
 To create secrets for an organization repository, you must have administrator access.

content/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces.md

@@ -96,3 +96,4 @@ Codespace secrets cannot be used:
 ## Further reading
 
 - "[AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces)"
+- "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#recommended-secrets)"

content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers.md

@@ -174,7 +174,7 @@ If none of the predefined configurations meets your needs, you can create a cust
 
    {% endnote %}
 
-   If multiple `devcontainer.json` files are found in the repository, they are listed in the codespace creation options page. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
+   If multiple `devcontainer.json` files are found in the repository, they are listed in the **Dev container configuration** dropdown on the codespace creation options page. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
 
    ![Screenshot of the codespace creation options page, showing a dropdown listing a choice of configuration files.](/assets/images/help/codespaces/configuration-file-choice.png)
 
@@ -194,6 +194,8 @@ If your repository already contains one or more `devcontainer.json` files, then
 
 If `.devcontainer/devcontainer.json` or `.devcontainer.json` exists, it will be the default selection in the list of available configuration files when you create a codespace. If neither file exists, the default dev container configuration will be selected by default.
 
+In the following screenshot, the repository does not contain `.devcontainer/devcontainer.json` or `.devcontainer.json` files, so the default dev container configuration is selected. However, two alternative configuration files have been defined in subdirectories of the `.devcontainer` directory, so these are listed as options.
+
 ![Screenshot of the "Dev container configuration" dropdown with the default configuration choice selected.](/assets/images/help/codespaces/configuration-file-choice-default.png)
 
 ### Editing the devcontainer.json file

content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/index.md

@@ -9,5 +9,6 @@ children:
   - /setting-a-minimum-specification-for-codespace-machines
   - /adding-features-to-a-devcontainer-file
   - /automatically-opening-files-in-the-codespaces-for-a-repository
+  - /specifying-recommended-secrets-for-a-repository
 ---
 

content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository.md

@@ -0,0 +1,70 @@
+---
+title: Specifying recommended secrets for a repository
+shortTitle: Specifying recommended secrets
+intro: 'You can add a setting to your dev container configuration that will prompt people to set specific secrets when they create a codespace.'
+permissions: People with write permissions to a repository can create or edit the codespace configuration.
+versions:
+  fpt: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Codespaces
+  - Set up
+---
+
+## About recommended secrets
+
+If a project needs user-specific secrets to be set up, you can prompt people to do this when they create a codespace. You do this by adding a setting to a dev container configuration file for the repository.
+
+After you specify recommended secrets, if people have not already created those secrets in their personal settings for {% data variables.product.prodname_codespaces %}, they will be prompted to do so when they use the advanced options method of creating a codespace. This is done on {% data variables.product.prodname_dotcom_the_website %} by clicking the **{% octicon "code" aria-hidden="true" %} Code** button, then clicking the **Codespaces** tab, then selecting {% octicon "kebab-horizontal" aria-label="Codespace repository configuration" %} and clicking **New with options**.
+
+![Screenshot of the options dropdown in the "{% data variables.product.prodname_codespaces %}" tab, with the option "New with options" highlighted.](/assets/images/help/codespaces/default-machine-type.png)
+
+Recommended secrets are listed at the bottom of the page.
+
+<img src="/assets/images/help/codespaces/recommended-secrets.png" style="max-height:50rem"  alt='Screenshot of the "Create codespace" page with four recommended secrets highlighted with a dark orange outline.' />
+
+{% note %}
+
+**Note**: The names of the recommended secrets are only listed on this page when the container configuration on the selected branch specifies these secrets.
+
+{% endnote %}
+
+Each recommended secret is displayed in one of three ways:
+
+* If the person has not set the recommended secret in their {% data variables.product.prodname_codespaces %} settings, an input box is displayed, allowing them to create the secret now. A description and link to more information are displayed if you have configured them. Entering a value is optional. 
+* If the person has already created the recommended secret but has not associated it with this repository, they can select a checkbox to add this association. Doing so is optional.
+* If the person has already created the recommended secret and associated it with this repository, a preselected checkbox is displayed.
+
+### When to specify recommended secrets for a project
+
+You should use recommended secrets for secrets that the user who creates the codespace, rather than the owner of the repository or organization, must provide. For example, if you have a public project, and users must provide a personal API key to run the application in your project, you can specify a recommended secret so that users will be prompted to provide the key as the value of the secret when they use the advanced options page to create a codespace. 
+
+Alternatively, for secrets that the owner of the repository or organization can provide, such as API keys shared across a team, you can set secrets at the level of the repository or organization. For more information, see "[AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces)."
+
+## Specifying recommended secrets in the dev container configuration
+
+{% data reusables.codespaces.edit-devcontainer-json %}
+1. Edit the `devcontainer.json` file, adding the `secrets` property at the top level of the file, within the enclosing JSON object. For example:
+
+   ```json{:copy}
+   "secrets": {
+     "NAME_OF_SECRET_1": {
+       "description": "This is the description of the secret.",
+       "documentationUrl": "https://example.com/link/to/info"
+     },
+     "NAME_OF_SECRET_2": { }
+   }
+   ```
+
+1. Add a property within `secrets` for each secret you want to recommend.  For example, change `NAME_OF_SECRET_1` and `NAME_OF_SECRET_2`, in the previous code example, to the names of the secrets that people should create in their personal settings for {% data variables.product.prodname_codespaces %}.
+1. Optionally, supply a description for each secret and a URL for more information about this secret. 
+
+   You can omit `description` and `documentationUrl`, as shown by `NAME_OF_SECRET_2` in the previous code example.
+
+1. Specify additional secrets, as required.
+1. Save the file and commit your changes to the required branch of the repository.
+
+## Further reading
+
+- "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository?tool=webui#creating-a-codespace-for-a-repository)"

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge.md

@@ -1,58 +0,0 @@
----
-title: Adding an "Open in GitHub Codespaces" badge
-shortTitle: Add a Codespaces badge
-intro: You can add a badge to a Markdown file in your repository which people can click to create a codespace.
-allowTitleToDifferFromFilename: true
-versions:
-  fpt: '*'
-  ghec: '*'
-type: how_to
-topics:
-  - Codespaces
-  - Set up
-redirect_from:
-  - /codespaces/setting-up-your-project-for-codespaces/adding-a-codespaces-badge
----
-
-## Overview
-
-Adding an "Open in {% data variables.product.prodname_github_codespaces %}" badge to a Markdown file gives people an easy way to create a codespace for your repository.
-
-![Screenshot of an "Open in {% data variables.product.prodname_github_codespaces %}" badge on a README page.](/assets/images/help/codespaces/codespaces-badge-on-readme.png)
-
-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 "[AUTOTITLE](/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**.
-
-## Creating an "Open in {% data variables.product.prodname_github_codespaces %}" badge
-
-{% data reusables.repositories.navigate-to-repo %}
-1. Under the repository name, click the button labeled with the name of the current branch and, in the dropdown menu, select the branch you want to create the badge for.
-
-   ![Screenshot of the expanded branch dropdown menu, listing various branches. The dropdown menu, labeled with a branch icon and "trunk," is highlighted with a dark orange outline.](/assets/images/help/codespaces/branch-drop-down.png)
-
-1. Click the **{% octicon "code" aria-label="The code icon" %} Code** button, then click the **Codespaces** tab.
-1. At the top right of the **Codespaces** tab, select {% octicon "kebab-horizontal" aria-label="Codespace repository configuration" %} and click **New with options**.
-
-   ![Screenshot of the options dropdown in the "{% data variables.product.prodname_codespaces %}" tab, showing the option "New with options."](/assets/images/help/codespaces/default-machine-type.png)
-
-1. 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 with dropdown menus for "Branch," "Dev container configuration," "Region," and "Machine type."](/assets/images/help/codespaces/advanced-options.png)
-
-1. Copy the URL from the browser's address bar.
-1. Add the following Markdown to, for example, the `README.md` file of your repository:
-
-   ```Markdown{:copy}
-   [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](COPIED-URL)
-   ```
-
-   For example:
-
-   ```Markdown
-   [![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.

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces.md

@@ -0,0 +1,105 @@
+---
+title: Facilitating quick creation and resumption of codespaces
+shortTitle: Facilitating codespace creation
+intro: You can add a link to take people straight to a page for creating a codespace, with your choice of options preconfigured. Alternatively you can link to the "Resume codespace" page.
+allowTitleToDifferFromFilename: true
+versions:
+  fpt: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Codespaces
+  - Set up
+redirect_from:
+  - /codespaces/setting-up-your-project-for-codespaces/adding-a-codespaces-badge
+  - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge
+---
+
+## Overview
+
+You can make it easy for people to work on your repository in a codespace by providing a link to the codespace creation page. One place you might want to do this is in the README file for your repository. For example, you can add the link to an "Open in {% data variables.product.prodname_github_codespaces %}" badge.
+
+![Screenshot of an "Open in {% data variables.product.prodname_github_codespaces %}" badge on a README page.](/assets/images/help/codespaces/codespaces-badge-on-readme.png)
+
+The link to the codespace creation page can include specific configuration options to help people create an appropriate codespace. People who use the link will be able to choose different options, if they want, before creating the codespace. For information about the available options, see "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)."
+
+Alternatively, you can link to the "Resume codespace" page, which provides a quick way for people to open a codespace they were working on recently.
+
+## Creating a link to the codespace creation page for your repository
+
+You can use these URLs to link to the codespace creation page for your repository. Replace the text in uppercase letters.
+
+- Create a codespace for the default branch of the repository:
+  `https://codespaces.new/OWNER/REPO-NAME`
+- Create a codespace for a specific branch of the repository:
+  `https://codespaces.new/OWNER/REPO-NAME/tree/BRANCH-NAME`
+- Create a codespace for the topic branch of a pull request:
+  `https://codespaces.new/OWNER/REPO-NAME/pull/PR-SHA`
+
+### Configuring more options
+
+You can use the "Share a deep link" option to configure more options for the codespace and build a custom URL, then copy a Markdown or HTML snippet for an "Open in {% data variables.product.prodname_github_codespaces %}" badge.
+
+{% data reusables.repositories.navigate-to-repo %}
+1. If you want to create a link for a branch other than the repository's default branch, under the repository name, click the button labeled with the name of the current branch. In the dropdown menu, select the branch for which you want to create a link.
+
+   ![Screenshot of the expanded branch dropdown menu, listing various branches. The dropdown menu, labeled with a branch icon and "trunk," is highlighted with a dark orange outline.](/assets/images/help/codespaces/branch-drop-down.png)
+
+1. Click the **{% octicon "code" aria-label="The code icon" %} Code** button, then click the **Codespaces** tab.
+1. To open the "Share codespace configuration" window, at the top right of the **Codespaces** tab, select {% octicon "kebab-horizontal" aria-label="Codespace repository configuration" %}, then click **Share a deep link**.
+
+   ![Screenshot of the options dropdown in the "{% data variables.product.prodname_codespaces %}" tab. The "Share a deep link" option is highlighted with an orange outline.](/assets/images/help/codespaces/share-deep-link.png)
+
+1. Optionally, to take users to a page where they can quickly resume a recent codespace or create a new one, select **Quick start**. For more information, see "[Creating a link to resume a codespace](#creating-a-link-to-resume-a-codespace)."
+1. Optionally, to specify a dev container configuration, select **Configuration file**, then use the dropdown menu to choose a configuration. If you don't specify a configuration, the default configuration for your repository is used. For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)."
+1. Under "Snippets," you can copy the URL you have built, or copy a Markdown or HTML snippet including an "Open in {% data variables.product.prodname_github_codespaces %}" badge. To copy the URL or snippet, select between the **URL**, **HTML**, and **Markdown** tabs, then click {% octicon "copy" aria-label="Copy text to the system clipboard" %}.
+
+   ![Screenshot of the "Share codespace configuration" window. Next to the "new codespace" URL, an icon of two overlapping squares is outlined in orange.](/assets/images/help/codespaces/copy-codespace-url.png)
+
+## Creating a link to resume a codespace
+
+You can create a link to a page for resuming your most recent codespace that matches the repository, branch, and other options specified in the URL.
+
+Add `?quickstart=1` to a `codespaces.new` URL, such as the URLs listed in the previous section of this article. This produces a URL that displays a "Resume codespace" page. 
+
+For example, the URL `https://codespaces.new/octo-org/octo-repo?quickstart=1` opens a page to allow you to resume your most recent codespace for the default branch of the `octo-org/octo-repo` repository.
+
+![Screenshot of the "Resume codespace" page showing the "Resume this codespace" and "Create a new one" buttons.](/assets/images/help/codespaces/resume-codespace.png)
+
+{% note %}
+
+**Notes**: 
+
+- If the `codespaces.new` URL already contains a query string, add `&quickstart=1` at the end of the query string.
+- This type of URL will always open a codespace in the {% data variables.product.prodname_vscode_shortname %} web client, even if this is not set as your default editor for {% data variables.product.prodname_github_codespaces %}.
+
+{% endnote %}
+
+If no matching codespaces are found, the page is titled "Create codespace" and a button is displayed for creating a new codespace with matching parameters.
+
+This type of URL is useful, for instance, in a README for your repository as it gives people a way of either creating a codespace, or resuming their codespace, in just a couple of clicks.
+
+## Creating an "Open in {% data variables.product.prodname_github_codespaces %}" badge
+
+{% tip %}
+
+**Tip:** You can use the "Share a deep link" option to create a Markdown or HTML snippet that includes an "Open in {% data variables.product.prodname_github_codespaces %}" badge with a custom URL. For more information, see "[Configuring more options](#configuring-more-options)."
+
+{% endtip %}
+
+1. Get the URL to the codespace creation page, or the "Resume codespace" page, as described in the previous sections.
+1. Add the following Markdown to, for example, the `README.md` file of your repository:
+
+   ```Markdown{:copy}
+   [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](URL)
+   ```
+
+   For example:
+
+   ```Markdown
+   [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/github/docs)
+   ```
+
+   The example Markdown is rendered like this:
+   
+   [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/github/docs)

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/index.md

@@ -7,7 +7,7 @@ versions:
   fpt: '*'
   ghec: '*'
 children:
-  - /adding-a-codespaces-badge
+  - /facilitating-quick-creation-and-resumption-of-codespaces
   - /setting-up-a-template-repository-for-github-codespaces
 ---
 

data/reusables/codespaces/edit-devcontainer-json.md

@@ -1 +1 @@
-1. {% data variables.product.prodname_github_codespaces %} for your repository may be configured in a `devcontainer.json` file. If your repository does not already contain a `devcontainer.json` file, you can add one now. See "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration)."
+1. You can configure the codespaces that are created for your repository by adding settings to a `devcontainer.json` file. If your repository doesn't already contain a `devcontainer.json` file, you can add one now. See "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration)."

data/reusables/codespaces/secrets-on-start.md

@@ -1 +1 @@
-Once you have created a secret, it will be available when you create a new codespace or restart the codespace. To use a secret that you've just created in a current codespace, you will need to stop the codespace and resume it. For information about stopping the codespace, see "[AUTOTITLE](/codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces#suspending-or-stopping-a-codespace)."
+Once you have created a secret, it will be available when you create a new codespace or restart the codespace. If you've created a secret on {% data variables.product.prodname_dotcom_the_website %} and you want to use it in a currently running codespace, stop the codespace and then restart it. For information about stopping the codespace, see "[AUTOTITLE](/codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces#suspending-or-stopping-a-codespace)."