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 must have a valid access token set in your codespace repository secrets under the name EXPERIMENTAL_CODESPACE_CACHE_TOKEN. The token must have 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 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.

Step 2: Create the workflow file

Create a workflow file in your repo that uses the github/codespaces-precache action.

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

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:
jobs:
  createPrebuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: github/codespaces-precache@v1.0.1
        with:
          regions: WestUs2
          sku_name: standardLinux32gb
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}