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

title, shortTitle, intro, versions, type, topics, product, miniTocMaxHeadingLevel

title	shortTitle	intro	versions	type	topics	product	miniTocMaxHeadingLevel
Managing prebuilds	Manage prebuilds	You can review, modify, and delete the prebuild configurations for your repository.	fpt ghec * *	how_to	Codespaces	{% data reusables.gated-features.codespaces %}	3

{% data reusables.codespaces.prebuilds-beta-note %}

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 workflow is 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
• Manually triggering the workflow

People with admin access to a repository can check the progress of prebuilds, edit, and delete prebuild configurations.

Viewing the progress of prebuilds

You can view the current status of the latest workflow run for each prebuild configuration you've set up on the {% data variables.product.prodname_codespaces %} page of your repository settings. For example, "Currently running" or "Last run 1 hour ago."

To see the log output for the latest prebuild workflow run, click See output.

This displays the output of the most recent run of the workflow in the Actions tab.

Alternatively, to view all prebuild workflow runs associated with the specified branch, click the ellipsis button and choose View runs from the dropdown menu.

This displays the workflow run history for prebuilds for the associated branch.

Editing a prebuild configuration

1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration you want to edit.

2. In the dropdown menu, click Edit.

   

3. Make the required changes to the prebuild configuration, then click Update.

Delete a prebuild configuration

Deleting a prebuild configuration also deletes all previously created prebuild templates for that configuration. As a result, shortly after you delete a configuration, prebuilds generated by that configuration will no longer be available when you create a new codespace.

After you delete a prebuild configuration, workflow runs for that configuration that have been queued or started will still run. They will be listed in the workflow run history, along with previously completed workflow runs.

1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration you want to delete.

2. In the dropdown menu, click Delete.

   

3. Click OK to confirm the deletion.

Manually trigger prebuilds

It may be useful to manually trigger a workflow run for a prebuild configuration. Generally this is only necessary if you are debugging a problem with the workflow for a prebuild configuration.

1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration whose workflow you want to trigger.

2. In the dropdown menu, click Manually trigger.

   

Allowing a prebuild to access external resources

By default, the {% data variables.product.prodname_actions %} workflow for a prebuild configuration can only access its own repository contents. Your project may use additional resources to build the development environment, such as files in other repositories, packages, GHCR images, and APIs. To allow your prebuild setup to access these resources, you will need to create a new personal account and then use this account to create a personal access token (PAT) with the appropriate scopes.

1. Create a new personal account on {% data variables.product.prodname_dotcom %}.

   {% warning %}

   Warning: Although you can generate the PAT using your existing personal account, we strongly recommend creating a new account with access only to the target repositories required for your scenario. This is because the access token's repository permission grants access to all of the repositories that the account has access to. For more information, see "Signing up for a new GitHub account" and "Security hardening for {% data variables.product.prodname_actions %}."

   {% endwarning %}

2. Give the new account read access to the required repositories. For more information, see "Managing an individual's access to an organization repository."

3. While signed into the new account, create a PAT with the repo scope. Optionally, if the prebuild will need to download packages from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}, also select the read:packages scope. For more information, see "Creating a personal access token."

   

   If the prebuild will use a package from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}, you will need to either grant the new account access to the package or configure the package to inherit the access permissions of the repository you are prebuilding. For more information, see "Configuring a package's access control and visibility."
   {% ifversion ghec %}1. Authorize the token for use with SAML single sign-on (SSO), so that it can access repositories that are owned by organizations with SSO enabled. For more information, see "Authorizing a personal access token for use with SAML single sign-on."

   

{% endif %}

1. Copy the token string. You will assign this to a {% data variables.product.prodname_codespaces %} repository secret.
2. Sign back into the account that has admin access to the repository.
3. In the repository for which you want to create {% data variables.product.prodname_codespaces %} prebuilds, create a new {% data variables.product.prodname_codespaces %} repository secret called CODESPACES_PREBUILD_TOKEN, giving it the value of the token you created and copied. For more information, see "Managing encrypted secrets for your repository and organization for {% data variables.product.prodname_codespaces %}."

The PAT will be used for all subsequent prebuild templates created for your repository. Unlike other {% data variables.product.prodname_codespaces %} repository secrets, the CODESPACES_PREBUILD_TOKEN secret is only used for prebuilding and will not be available to use in codespaces created from your repository.

Further reading

• "Troubleshooting prebuilds"