Run devbox with GitHub Actions

Prerequisites#

• A repository with GitHub Actions enabled and a Linux runner with Docker, such as GitHub-hosted ubuntu-24.04.

Set up#

Copy the workflow into your repository and replace the Check step with your own commands:

mkdir -p .github/workflows
cp workflow.yml .github/workflows/devbox.yml

It runs on pull requests and on pushes to main.

The workflow runs ghcr.io/hambn/devbox:ubuntu-full. Replace the tag with @sha256:<digest> to pin one build.

Variables#

None. Add secrets to individual steps with env: and ${{ secrets.<NAME> }}, not to the whole job.

Workspace#

The runner mounts the checkout at /__w/<repo>/<repo> and sets HOME=/github/home. The job runs as root (options: --user root) because the runner's files belong to its own user (UID 1001) and actions/checkout does not support (opens in new tab) a non-root container user.

Files#

• workflow.yml: pull request and main push workflow with a devbox job container.

Limitations#

• Each job pulls the image on a fresh runner, which adds time before the first step.
• JavaScript actions run inside the job container; on Alpine variants they work only on x64 runners.

# Copy to .github/workflows/devbox.yml and replace the check commands with your own.
name: devbox

on:
  pull_request:
  push:
    branches: [main]

permissions: {}

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    name: Check in devbox
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
    container:
      image: ghcr.io/hambn/devbox:ubuntu-full
      # The runner's workspace and temp files belong to its own user (UID 1001), and
      # actions/checkout does not support a non-root container user.
      options: --user root
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Check
        run: |
          go version
          node --version
          python3 --version