diff --git a/.gitignore b/.gitignore index 0a4285c2a2..8b780e4e2e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ .search-cache .DS_Store .env +.vscode/settings.json /node_modules/ npm-debug.log coverage/ diff --git a/content/codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds.md b/content/codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds.md index 1449eb0c34..2ea55b3d1d 100644 --- a/content/codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds.md +++ b/content/codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds.md @@ -16,7 +16,7 @@ product: '{% data reusables.gated-features.codespaces %}' 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. -Whenever you push changes to your repository, {% data variables.product.prodname_codespaces %} uses {% data variables.product.prodname_actions %} to automatically update your prebuilds. +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 machine type dialog box that's displayed when you create a codespace and multiple machine types are available. @@ -30,9 +30,9 @@ Use of codespaces created using prebuilds is charged at the same rate as regular ## About pushing changes to prebuild-enabled branches -Each push to a branch that has a prebuild configuration results in a {% data variables.product.prodname_dotcom %}-managed Actions workflow run to update the prebuild template. The prebuild workflow has a concurrency limit of one workflow run at a time for a given prebuild configuration, unless changes were made that affect the dev container configuration for the associated repository. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)." If a run is already in progress, the workflow run that was queued most recently queued will run next, after the current run completes. +By default, each push to a branch that has a prebuild configuration results in a {% data variables.product.prodname_dotcom %}-managed Actions workflow run to update the prebuild template. The prebuild workflow has a concurrency limit of one workflow run at a time for a given prebuild configuration, unless changes were made that affect the dev container configuration for the associated repository. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)." If a run is already in progress, the workflow run that was queued most recently queued will run next, after the current run completes. -This means that if there are very frequent pushes to your repository, prebuild creation will occur at least as often as it takes to run the prebuild workflow. That is, if your workflow run typically takes one hour to complete, prebuilds will be created for your repository roughly hourly, if the run succeeds, or more often if there were pushes that change the dev container on the branch. +With the prebuild template set to be updated on each push, it means that if there are very frequent pushes to your repository, prebuild template updates will occur at least as often as it takes to run the prebuild workflow. That is, if your workflow run typically takes one hour to complete, prebuilds will be created for your repository roughly hourly, if the run succeeds, or more often if there were pushes that change the dev container configuration on the branch. For example, let's imagine 5 pushes are made, in quick succession, against a branch that has a prebuild configuration. In this situation: diff --git a/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md b/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md index 32ed69a742..7d83636d77 100644 --- a/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md +++ b/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md @@ -58,6 +58,14 @@ 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. + + * **Every push** - 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** - This ensure 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** - This can reduce consumption of Actions minutes, and reduce the amount of time that 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. + + ![The prebuild trigger options](/assets/images/help/codespaces/prebuilds-triggers.png) ---------SCREENSHOT TO BE ADDED + 1. Click **Create**. The prebuild configuration is listed on the {% data variables.product.prodname_codespaces %} page of your repository settings. A {% data variables.product.prodname_actions %} workflow is queued and then run to create prebuild templates, based on the branch you selected, in the regions you specified. diff --git a/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md b/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md index 27e2c823c0..229db25ffc 100644 --- a/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md +++ b/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md @@ -16,14 +16,18 @@ miniTocMaxHeadingLevel: 3 ## Checking, changing, and deleting your prebuild configurations -The prebuilds that you configure are created and updated using a {% data variables.product.prodname_actions %} workflow, managed by the {% data variables.product.prodname_codespaces %} service. +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. -The workflow is triggered by these events: +Depending on the settings in a prebuild configuration, the workflow to update the prebuild template may be triggered by these events: * Creating or updating the prebuild configuration * Pushing a commit or a pull request to a branch that's configured to have prebuilds +* Changing any of the dev container configuration files +* A schedule that you've defined in the prebuild configuration * Manually triggering the workflow +The settings in the prebuild configuration determine which events automatically trigger an update of the prebuild template. For more information, see "[Configuring prebuilds](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-a-prebuild)." + People with admin access to a repository can check the progress of prebuilds, edit, and delete prebuild configurations. ### Viewing the progress of prebuilds diff --git a/content/codespaces/troubleshooting/troubleshooting-prebuilds.md b/content/codespaces/troubleshooting/troubleshooting-prebuilds.md index 16a6369822..dfbd2ddd5c 100644 --- a/content/codespaces/troubleshooting/troubleshooting-prebuilds.md +++ b/content/codespaces/troubleshooting/troubleshooting-prebuilds.md @@ -42,15 +42,15 @@ cat /workspaces/.codespaces/shared/environment-variables.json | jq '.ACTION_NAME You may notice that sometimes, when you create a new codespace from a prebuild-enabled branch, the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is not displayed in the dialog box for choosing a machine type. This means that prebuilds are not currently available. -Each time you push to a prebuild-enabled branch, the prebuild template is updated. If the push involves a change to the dev container then, while the update is in progress, the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is removed from the machine types dialog box. During this time you can still create codespaces without a prebuild template. +By default, each time you push to a prebuild-enabled branch, the prebuild template is updated. If the push involves a change to the dev container then, while the update is in progress, the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is removed from the machine types dialog box. During this time you can still create codespaces without a prebuild template. If required, you can reduce the occasions on which prebuilds are unavailable for a repository by setting the 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)." -If your branch is not specifically enabled for prebuilds it may still benefit from prebuilds if it was branched from a prebuild-enabled branch. However, if the dev container is changed on your branch, so that it's not the same as the dev container on the base branch, prebuilds will no longer be available on your branch. +If your branch is not specifically enabled for prebuilds it may still benefit from prebuilds if it was branched from a prebuild-enabled branch. However, if the dev container configuration is changed on your branch, so that it's not the same as the dev container configuration on the base branch, prebuilds will no longer be available on your branch. Here are things to check if the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is not displayed for a particular branch: * Confirm that a prebuild configuration exists for this branch. If you’re not a repository administrator, you'll need to reach out to one to confirm this. * Confirm that the prebuild configuration includes your region. -* Check whether a change to the dev container configuration was pushed to the prebuild-enabled branch recently. If so, you will have to wait until the prebuild workflow run for this push completes before prebuilds are available again. +* Check whether a change to the dev container configuration was pushed to the prebuild-enabled branch recently. If so, you will typically have to wait until the prebuild workflow run for this push completes before prebuilds are available again. * If no configuration changes were recently made, go to the **Actions** tab of your repository, click **{% octicon "codespaces" aria-label="The Codespaces icon" %} {% data variables.product.prodname_codespaces %} Prebuilds** in the workflows list, and check that prebuild workflow runs for the branch are succeeding. If latest runs of a workflow failed, and one or more of these failed runs contained changes to the dev container, then there will be no available prebuilds for the associated branch. ## Further reading diff --git a/data/reusables/codespaces/billing-for-prebuilds.md b/data/reusables/codespaces/billing-for-prebuilds.md index 06a3671163..c7c37eea5c 100644 --- a/data/reusables/codespaces/billing-for-prebuilds.md +++ b/data/reusables/codespaces/billing-for-prebuilds.md @@ -1,5 +1,7 @@ -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)." +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)." +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)." + +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)." 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.