Skip to main content

Snapshot Runners

WarpBuild allows you to take snapshots of your runner VMs at any point during your workflow, enabling faster consecutive runs by reusing these snapshots.

Prerequisites​

  • Supported Platforms: Snapshot Runners feature is supported only on WarpBuild Linux runners at the moment.
  • Unsupported Platforms: BYOC based runners, container-based runner images and Mac runners are not supported.

Usage​

To use WarpSnapshot in your workflow, add the following step to your .github/workflows/{workflow_name}.yml file, preferably at the end of the job:

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-2x;snapshot.key=unique-snapshot-alias
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      # Add your build and test steps here
      - name: Create snapshot
        uses: WarpBuilds/snapshot-save@v1
        with:
          alias: "unique-snapshot-alias"
          fail-on-error: true
          wait-timeout-minutes: 60

Invoking the action creates the snapshot of the runner. To use the snapshot in subsequent runs, specify the snapshot alias in the runs-on field of the job as shown above.

If the runner machine is made from a snapshot, it will have an environment variable WARPBUILD_SNAPSHOT_KEY set to the alias of the snapshot.

Inputs​

  • alias (Required): A unique alias for the snapshot, helping you easily identify and manage your snapshots.
  • fail-on-error (Optional): If set to true, the action will fail if an error occurs during snapshot creation. Default is true.
  • wait-timeout-minutes (Optional): The maximum time (in minutes) to wait for the snapshot to be created. Default is 30 minutes.

Conditional Snapshot Usage​

You can conditionally use snapshot runners by configuring the runs-on field in your workflow:

jobs:
  build:
    runs-on: ${{ contains(github.event.head_commit.message, '[warp-no-snapshot]') ? 'warp-ubuntu-latest-x64-2x' : 'warp-ubuntu-latest-x64-2x;snapshot.key=unique-snapshot-alias' }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      # Add your build and test steps here
      - name: Create snapshot
        uses: WarpBuilds/snapshot-save@v1
        with:
          alias: 'unique-snapshot-alias'

Advanced Conditional Logic​

For more complex scenarios, such as determining whether to use a standard or snapshot runner based on branch protection or other conditions, use the following setup:

jobs:
  determine-runner:
    runs-on: ubuntu-latest
    outputs:
      runner: ${{ steps.set-runner.outputs.runner }}
    steps:
      - name: Determine Branch Protection
        id: branch-protection
        run: |
          branch=$(echo "${{ github.ref }}" | sed 's|refs/heads/||')
          echo "Branch: $branch"
          response=$(curl -s -o /dev/null -w "%{http_code}" \
            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
            -H "Accept: application/vnd.github.v3+json" \
            "https://api.github.com/repos/${{ github.repository }}/branches/$branch/protection")
          if [ $response -eq 200 ]; then
            echo "Branch is protected"
            echo "runner=warp-ubuntu-latest-x64-8x;snapshot.key=unique-snapshot-alias" >> $GITHUB_OUTPUT
          else
            echo "Branch is not protected"
            echo "runner=warp-ubuntu-latest-x64-8x" >> $GITHUB_OUTPUT
          fi
  build:
    needs: determine-runner
    runs-on: ${{ needs.determine-runner.outputs.runner }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      # Add your build and test steps here
      - name: Create snapshot
        uses: WarpBuilds/snapshot-save@v1
        with:
          alias: "unique-snapshot-alias"

Cleanup Script​

It is highly recommended to include a cleanup step to remove credentials and sensitive information before creating a snapshot. This can be done by adding a cleanup script before the snapshot step:

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-2x;snapshot.key=unique-snapshot-alias
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      # Add your build and test steps here
      - name: Cleanup VM
        run: |
          rm -rf $HOME/.ssh
          rm -rf $HOME/.aws
      - name: Create snapshot
        uses: WarpBuilds/snapshot-save@v1
        with:
          alias: "unique-snapshot-alias"
          fail-on-error: true
          wait-timeout-minutes: 60

Common cleanup commands​

Remove untracked files and directories:

It might be useful to remove some secret files that were added during the job, before making a snapshot.

git clean -ffdx
  • git clean: removes untracked files from the local git repo.
  • -f (force): forces the removal of files and directories.
  • -f (force again): if git config clean.requireForce true is present, some files may not be removed without this flag.
  • -d (directories): removes directories not just files.
  • -x (ignore .gitignore): removes files and directories that are ignored by git.

Security​

Public Repositories​

When using public repositories, ensure that no sensitive information (such as cloud credentials) is stored in the snapshot. This is crucial as others may access the snapshot using the alias in a PR workflow run.

Private Repositories​

WarpBuild provisions runners at the organization level, and GitHub may allocate a runner intended for snapshot jobs to different jobs within the organization. This could expose sensitive information to other users in the organization. It is recommended to use the cleanup script to remove sensitive data before creating a snapshot.

Additional Notes​

BYOC based snapshot runners will be launched soon.