Merge pull request #28324 from github/codespaces-prebuilds-ga

[06-15-2022] Codespace prebuilds GA (inc template history and failure notification)

content/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces.md

@@ -42,7 +42,6 @@ If you purchased {% data variables.product.prodname_enterprise %} through a Micr
 
 ### Billing for {% data variables.product.prodname_codespaces %} prebuilds
 
-{% data reusables.codespaces.prebuilds-beta-note %}
 
 {% data reusables.codespaces.billing-for-prebuilds %} 
 

content/codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds.md

@@ -1,7 +1,7 @@
 ---
 title: About Codespaces prebuilds
 shortTitle: About prebuilds
-intro: Codespaces prebuilds help to speed up the creation of new codespaces.
+intro: Codespaces prebuilds help to speed up the creation of new codespaces for large or complex repositories.
 versions:
   fpt: '*'
   ghec: '*'
@@ -10,15 +10,13 @@ topics:
 product: '{% data reusables.gated-features.codespaces %}'
 ---
 
-{% data reusables.codespaces.prebuilds-beta-note %}
-
 ## Overview
 
-Prebuilding your codespaces allows you to be more productive and access your codespace faster, regardless of the size and complexity of your project. This is because any source code, editor extensions, project dependencies, commands, and configurations have already been downloaded, installed, and applied before you create a codespace for your project. Think of a prebuild as a "ready-to-go" template for a codespace. 
+Prebuilding your codespaces allows you to be more productive and access your codespace faster, particularly if your repository is large or complex and new codespaces currently take more than 2 minutes to start. This is because any source code, editor extensions, project dependencies, commands, and configurations have already been downloaded, installed, and applied before you create a codespace for your project. Think of a prebuild as a "ready-to-go" template for a codespace. 
 
 By default, whenever you push changes to your repository, {% data variables.product.prodname_codespaces %} uses {% data variables.product.prodname_actions %} to automatically update your prebuilds.
 
-When prebuilds are available for a particular branch of a repository, and for your region, you'll see the "{% octicon "zap" aria-label="The zap icon" %} Prebuild ready" label in the list of machine type options when you create a codespace. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
+When prebuilds are available for a particular branch of a repository, and for your region, you'll see the "{% octicon "zap" aria-label="The zap icon" %} Prebuild ready" label in the list of machine type options when you create a codespace. If a prebuild is still being created, you will see the "{% octicon "history" aria-label="The history icon" %} Prebuild in progress" label. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
 
 ![The dialog box for choosing a machine type](/assets/images/help/codespaces/choose-custom-machine-type.png)
 

content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md

@@ -13,8 +13,6 @@ product: '{% data reusables.gated-features.codespaces %}'
 permissions: People with admin access to a repository can configure prebuilds for the repository.
 ---
 
-{% data reusables.codespaces.prebuilds-beta-note %}
-
 You can set up a prebuild configuration for a specific branch of your repository.
 
 Any branch created from a prebuild-enabled base branch will typically also get assigned a prebuild during codespace creation. This is true if the dev container on the branch is the same as on the base branch. This is because the majority of the prebuild configuration for branches with the same dev container configuration are identical, so developers can benefit from faster codespace creation times on those branches also. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)."
@@ -38,7 +36,7 @@ Before you can configure prebuilds for your project the following must be true:
 
    ![The 'Set up prebuilds' button](/assets/images/help/codespaces/prebuilds-set-up.png)
 
-1. Choose the branch for which you want to set up a prebuild. 
+1. Choose the branch for which you want to set up a prebuild.
 
    ![The Branch drop-down menu](/assets/images/help/codespaces/prebuilds-choose-branch.png)
 
@@ -48,7 +46,15 @@ Before you can configure prebuilds for your project the following must be true:
 
    {% endnote %}
 
-1. Choose the regions in which you want to set up a prebuild. Developers must be located in a region you select to be able to create codespaces from a prebuild. Alternatively, select **All regions**.
+1. Choose how you want to automatically trigger updates of the prebuild template.
+
+   * **Every push** (the default setting) - With this setting, prebuild configurations will be updated on every push made to the given branch. This will ensure that codespaces generated from a prebuild template always contain the latest codespace configuration, including any recently added or updated dependencies.
+   * **On configuration change** - With this setting, prebuild configurations will be updated every time associated configuration files for a given repo and branch are updated. This ensures that changes to the dev container configuration files for the repository are used when a codespace is generated from a prebuild template. The Actions workflow that updates the prebuild template will run less often, so this option will use fewer Actions minutes. However, this option will not guarantee that codespaces always include recently added or updated dependencies, so these may have to be added or updated manually after a codespace has been created.
+   * **Scheduled** - With this setting, you can have your prebuild configurations update on a custom schedule that's defined by you. This can reduce consumption of Actions minutes, however, with this option, codespaces may be created that do not use the latest dev container configuration changes.
+
+   ![The prebuild trigger options](/assets/images/help/codespaces/prebuilds-triggers.png)
+
+1. Select **Reduce prebuild available to only specific regions** to limit access to your prebuilt image, then select which regions you want it available in. Developers can only create codespaces from a prebuild if they are located in a region you select. By default, your prebuilt image is available to all regions where codespaces is available and storage costs apply for each region.
 
    ![The region selection options](/assets/images/help/codespaces/prebuilds-regions.png)
 
@@ -60,13 +66,17 @@ Before you can configure prebuilds for your project the following must be true:
 
    {% endnote %}
 
-1. Choose how you want to automatically trigger updates of the prebuild template.
+1. Set the number of prebuild template versions to be retained. You can input any number between 1 and 5. The default number of saved versions is 2, which means that only the latest template version and the previous version are saved.
 
-   * **Every push** (the default setting) - With this setting, prebuild configurations will be updated on every push made to the given branch. This will ensure that codespaces generated from a prebuild template always contain the latest codespace configuration, including any recently added or updated dependencies.
-   * **On configuration change** - With this setting, prebuild configurations will be updated every time associated configuration files for a given repo and branch are updated. This ensures that changes to the dev container configuration files for the repository are used when a codespace is generated from a prebuild template. The Actions workflow that updates the prebuild template will run less often, so this option will use fewer Actions minutes. However, this option will not guarantee that codespaces always include recently added or updated dependencies, so these may have to be added or updated manually after a codespace has been created.
-   * **Scheduled** - With this setting, you can have your prebuild configurations update on a custom schedule that's defined by you. This can reduce consumption of Actions minutes, and reduce the amount of time during which prebuilds are unavailable because they are being updated. However, with this option, codespaces may be created that do not use the latest dev container configuration changes.
+   Depending on your prebuild trigger settings, your prebuild template could change with each push or on each dev container configuration change. Retaining older versions of prebuild templates enables you to create a prebuild from an older commit with a different dev container configuration than the current prebuild template. Since there is a storage cost associated with retaining prebuild template versions, you can choose the number of versions to be retained based on the needs of your team. For more information on billing, see "[About billing for {% data variables.product.prodname_codespaces %}](/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces#codespaces-pricing)."
 
-   ![The prebuild trigger options](/assets/images/help/codespaces/prebuilds-triggers.png)
+   If you set the number of prebuild template versions to save to 1, {% data variables.product.prodname_codespaces %} will only save the latest version of the prebuild template and will delete the older version each time the template is updated. This means you will not get a prebuilt codespace if you go back to an older dev container configuration.
+
+   ![The prebuild template history setting](/assets/images/help/codespaces/prebuilds-template-history-setting.png)
+
+1. Add users or teams to notify when the prebuild workflow run fails for this configuration. You can begin typing a username, team name, or full name, then click the name once it appears to add them to the list. The users or teams you add will receive an email when prebuild failures occur, containing a link to the workflow run logs to help with further investigation.
+
+   ![The prebuild failure notification setting](/assets/images/help/codespaces/prebuilds-failure-notification-setting.png)
 
 1. Click **Create**.
 

content/codespaces/prebuilding-your-codespaces/index.md

@@ -15,5 +15,4 @@ children:
   - /managing-prebuilds
   - /testing-dev-container-changes
 ---
- 
-{% data reusables.codespaces.prebuilds-beta-note %}
+

content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md

@@ -12,8 +12,6 @@ product: '{% data reusables.gated-features.codespaces %}'
 miniTocMaxHeadingLevel: 3
 ---
 
-{% data reusables.codespaces.prebuilds-beta-note %}
-
 ## Checking, changing, and deleting your prebuild configurations
 
 The prebuilds that you configure for a repository are created and updated using a {% data variables.product.prodname_actions %} workflow, managed by the {% data variables.product.prodname_codespaces %} service. 

content/codespaces/prebuilding-your-codespaces/testing-dev-container-changes.md

@@ -14,8 +14,6 @@ product: '{% data reusables.gated-features.codespaces %}'
 permissions: People with write permissions to a repository can create or edit the dev container configuration for a branch.
 ---
 
-{% data reusables.codespaces.prebuilds-beta-note %}
-
 Any changes you make to the dev container configuration for a prebuild-enabled branch will result in an update to the codespace configuration and the associated prebuild template. It’s therefore important to test such changes in a codespace from a test branch before committing your changes to a branch of your repository that's actively used. This will ensure you’re not introducing breaking changes for your team.
 
 For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)."

content/codespaces/troubleshooting/troubleshooting-prebuilds.md

@@ -12,8 +12,6 @@ product: '{% data reusables.gated-features.codespaces %}'
 miniTocMaxHeadingLevel: 3
 ---
 
-{% data reusables.codespaces.prebuilds-beta-note %}
-
 For more information about {% data variables.product.prodname_codespaces %} prebuilds, see "[Prebuilding your codespaces](/codespaces/prebuilding-your-codespaces)."
 
 ## Checking whether a codespace was created from a prebuild?

data/reusables/codespaces/about-billing-for-codespaces.md

@@ -1 +0,0 @@
-{% data variables.product.prodname_codespaces %} is free to use during the beta. When {% data variables.product.prodname_codespaces %} becomes generally available, you will be billed for storage and compute usage.

data/reusables/codespaces/beta-functionality-limited.md

@@ -1,5 +0,0 @@
-During the beta, functionality is limited.
-- {% data reusables.codespaces.use-chrome %}
-- Only a single size of codespace is available.
-- Only Linux containers are supported.
-- A codespace is not fully resumable. Processes that were running at the time the codespace was stopped will not be restarted.

data/reusables/codespaces/billing-for-prebuilds.md

@@ -1,7 +1,7 @@
 By default, a {% data variables.product.prodname_actions %} workflow is triggered every time you create or update a prebuild template, or push to a prebuild-enabled branch. As with other workflows, while prebuild workflows are running they will either consume some of the Actions minutes included with your account, if you have any, or they will incur charges for Actions minutes. For more information about pricing for Actions minutes, see "[About billing for {% data variables.product.prodname_actions %}](/billing/managing-billing-for-github-actions/about-billing-for-github-actions)." 
 
-If you are an organization owner, you can track usage of prebuild workflows by downloading a {% data variables.product.prodname_actions %} usage report for your organization. You can identify workflow runs for prebuilds by filtering the CSV output to only include the workflow called "Create Codespaces Prebuilds." For more information, see "[Viewing your {% data variables.product.prodname_actions %} usage](/billing/managing-billing-for-github-actions/viewing-your-github-actions-usage#viewing-github-actions-usage-for-your-organization)."
+Alongside {% data variables.product.prodname_actions %} minutes, you will also be billed for the storage of prebuild templates associated with each prebuild configuration for a given repository and region. Storage of prebuild templates is billed at the same rate as storage of codespaces. For more information, see "[Calculating storage usage](#calculating-storage-usage)."
 
-To reduce consumption of Actions minutes, you can set a prebuild template to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. For more information, see "[Configuring prebuilds](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-a-prebuild)." 
+To reduce consumption of Actions minutes, you can set a prebuild template to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. You can also manage your storage usage by adjusting the number of template versions to be retained for your prebuild configurations. For more information, see "[Configuring prebuilds](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-a-prebuild)."
 
-While {% data variables.product.prodname_codespaces %} prebuilds is in beta there is no charge for storage of templates. When prebuilds become generally available, you will be billed for storing prebuild templates for each prebuild configuration in each region selected for that configuration. 
+If you are an organization owner, you can track usage of prebuild workflows and storage by downloading a {% data variables.product.prodname_actions %} usage report for your organization. You can identify workflow runs for prebuilds by filtering the CSV output to only include the workflow called "Create Codespaces Prebuilds." For more information, see "[Viewing your {% data variables.product.prodname_actions %} usage](/billing/managing-billing-for-github-actions/viewing-your-github-actions-usage#viewing-github-actions-usage-for-your-organization)."

data/reusables/codespaces/prebuilds-beta-note.md

@@ -1,5 +0,0 @@
-{% note %}
-
-**Note:** The ability to prebuild codespaces is currently in beta and subject to change. 
-
-{% endnote %}

data/reusables/codespaces/unsupported-repos.md

@@ -1 +0,0 @@
-During the beta, private repositories owned by organizations or any repositories owned by an organization that requires SAML single sign-on are not supported.