This action establishes a BinderHub session, and exposes the Jupyter server information to the current job. This makes it possible to use BinderHub for remote execution within a GitHub Actions workflow.

• Configure the action to point it to a Binder-ready repository (and optionally a BinderHub if different from mybinder.org).
• When the action runs, it will:
• Create a Binder session using that configuration.
• Export environment variables you can use in subsequent actions to run code in the Binder environment.
• When the GitHub Workflow completes, the BinderHub server will be shut down.

When the action is complete, you'll have a running Binder session that you can use to run code in your GitHub Workflow. It will output two environment variables you can use to execute code in that Binder session:

• JUPYTER_BASE_URL: The URL of the Jupyter server running in BinderHub.
• JUPYTER_TOKEN: The authentication token needed to execute code on that server.

Use these tokens in subsequent actions in the GitHub workflow. For example, Jupyter Book and MyST Documents automatically use the values of these environment variables to choose where they execute code. If you ensure the JUPYTER_* variables are in the global environment when a Jupyter Book is built, it will use the BinderHub to execute code.

Required The URL of the BinderHub.

The ORG/REPO identifying a GitHub repository. Defaults to $GITHUB_REPO if not set.

The Git reference identifying a Git revision, e.g. branch name. Defaults to $GITHUB_REF if not set.

A BinderHub build token, if required.

The URL of the started Jupyter Server.

The token of the started Jupyter Server.

name: Build on BinderHub

on:
  push:
jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      # Sets the JUPYTER_BASE_URL and JUPYTER_TOKEN env vars
      - uses: 2i2c-org/clinder@v1
        with:
          hub-url: https://mybinder.org/
      - uses: actions/setup-node@v4
        with:
          node-version: 20.x
      - name: Install MyST Markdown
        run: npm install -g mystmd
      - name: Build MyST Project
        run: myst build --site --strict --execute

See https://github.com/2i2c-org/clinder/blob/main/packages/clinder/README.md

This monorepoe contains three packages:

• binderhub-client-next — a fork of @jupyterhub/binderhub-client that supports running in a Node.js environment.
• clinder-action — a GitHub action that spins up and tears down a BinderHub instance.- clinder — a CLI to start up and tear down a BinderHub instance locally.

binderhub-client-next is a private package, and is bundled into the other packages. We use esbuild to bundle dependencies and transpile to CJS.

Unfortunately, various dependencies are CommonJS only, so we cannot trivially transpile to ESM. However, ESM is nicer to author, so we use ESM for the package definitions.

1. Merge to main with the new version in package.json
2. Create a GitHub release with tag cli-vX.X.X

1. Merge to main with a branch containing the built action npm run build -w packages/clinder-action
2. Create a GitHub release with the tag action-vX.

This repo doesn't yet add any testing for the action or the CI packages. This is primarily because the intention is to use the upstream @jupyterhub/binderhub-client package, which itself should be tested. Whilst we can test the CLI in time, it remains out of scope.

The action is tested in CI, which ensures that a remote Jupyter Book is running in a non-CI environment.