codespaces-precache

Experimental feature. A limited number of organizations/repositories will be admitted into a closed private beta. You can learn more and ask to sign up for the private preview here.

Prerequisites

Your organization must have been granted access to this experimental feature in order to use this action.

Step 1: Set up access token

In order to use this action, you will need to create a valid access token and set it in your codespace repository secrets under the name EXPERIMENTAL_CODESPACE_CACHE_TOKEN. The token will need access to your target repository for precached codespaces.

Step 1a: Generate access token

The token can be generated for any user. However, we highly recommend using a bot user with permission only to your target repository, or creating a new user and granting them permission to the target repository. This is because the access token repo permission grants access to all repositories the user has access to.

Once you have a target user with narrowly-scoped repository permissions, Create a personal access token with only the repo permission selected.

Step 1b: Add the access token as a repository secret

Create a repository secret. In repository settings, under the Secrets tab and Codespaces sub-menu option, create a secret with a name of EXPERIMENTAL_CODESPACE_CACHE_TOKEN and a value of the token you just created. This secret value will be used in the precaching process to set up your precached codespaces. The url to create the secret is https://github.com/[organization name]/[repository name]/settings/secrets/codespaces/new.

Step 2: Create the workflow file

Create a workflow file in your repo that uses the github/codespaces-precache action. The file should be in the .github/workflows directory.

Properties

Environment properties

The GITHUB_TOKEN variable needs to be added in the env to use this action. GITHUB_TOKEN is a token automatically generated by GitHub to authenticate the action. Read more about GITHUB_TOKEN here.

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Input properties

The following properties can be added as input properties using jobs.<job_id>.steps[*].with

name	required?	description
regions	yes	Separated region(s) to create cached codespaces in. Multiple regions can be specified, separated by spaces. Valid regions are: WestUs2 EastUs WestEurope SouthEastAsia
sku_name	yes	Machine type for the cached codespaces. Example: standardLinux32gb

Valid Sku names

Cores	Sku name
2-core	basicLinux32gb
4-core	standardLinux32gb
8-core	premiumLinux
16-core	largePremiumLinux
32-core	xLargePremiumLinux*

*Contact us to get access

See sku pricing info for more.

Other input properties

There are 2 additional input parameters for GitHub Codespaces developer use only: target and target_url. Access is required to use these parameters.

Standard Template

name: precache codespace
on:
  push:
    branches:
      - main
  workflow_dispatch:
permissions:
  content: write
jobs:
  createPrebuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: github/codespaces-precache@v1-stable
        with:
          regions: WestUs2
          sku_name: standardLinux32gb
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

We recommend you use the v1-stable version of the action, which will include the latest stable features, fixes, and patches.

Troubleshooting

I set up the action, how do I know if it worked?

Check the action logs for an error message or a success response. It may take some time to set up the first time, so wait a few minutes after seeing a success and try creating a codespace to see if it is created from a prebuild. Note that if you have multiple regions listed, each will be set up separately, so a partial failure is possible if some succeed and some fail.

Action failure looks like:

Action success response looks like:

How do I know if my new codespace was created from a prebuild?

There's an environment value set when you first create the codespace. You can paste this command into the built-in terminal:

$ cat /workspaces/.codespaces/shared/environment-variables.json | jq '.ACTION_NAME'
"createFromPrebuild"

If the output is "createFromPrebuild" it was newly created from a prebuild.

Can my postCreateCommand be run as part of the prebuild process?

We recommend updating your devcontainer.json to use onCreateCommand for any commands you want to run as part of the prebuild process, which will happen before the codespace gets assigned to a user. postCreateCommand will still run after a codespace is created and is therefore a good place to do any initialization that's specific to the user to whom the codespace is assigned.