GitHub Action × Bisque

Mention @bisque-cloud in a comment on a pull request and the reviewers get a watchable walkthrough of it, linked in a reply a few minutes later. Publish a release and its notes gain the same. It runs in your repository's GitHub Actions on your Claude plan, and it needs no Bisque account: each explainer lands on your repository's own channel, bisque.today/p/{owner}/{repo}.

Hand it to your agent

Set up the Bisque pull request explainer on this repository by following https://bisque.today/docs/github.md

Your agent does the steps below. One of them is yours, because only you can sign in to your Claude account.

Steps

1. Make a Claude Code token and store it as a repository secret. This is the person's step. In a terminal where claude is installed:

   claude setup-token
   gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo OWNER/REPO
   

   The first command opens a browser to sign in and prints a token. Paste it when the second asks. An agent should ask the person to run both and wait, and never read the token itself.

   No Claude plan? Set one provider API key instead, as ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY or XAI_API_KEY, and pass it as anthropic-api-key, openai-api-key, google-api-key or xai-api-key in the workflow below in place of claude-code-oauth-token.

2. Add the workflow as .github/workflows/explain-pull-requests.yml:

   name: Pull request explainer
   
   on:
     issue_comment:
       types: [created]
   
   permissions:
     contents: read
     pull-requests: write # post the watch link as a comment
     issues: write # react to the comment that mentions @bisque-cloud
     id-token: write # publish as this repository, no Bisque account
   
   jobs:
     explain:
       if: >-
         github.event.issue.pull_request &&
         contains(github.event.comment.body, '@bisque-cloud')
       runs-on: ubuntu-latest
       steps:
         - name: Check the mention and write access, and react so the commenter knows
           id: mention
           env:
             GH_TOKEN: ${{ github.token }}
             REPO: ${{ github.repository }}
             ACTOR: ${{ github.actor }}
             COMMENT_ID: ${{ github.event.comment.id }}
             BODY: ${{ github.event.comment.body }}
           run: |
             if ! grep -Eiq '(^|[[:space:]])@bisque-cloud([[:space:].,!?;:]|$)' <<<"$BODY"; then
               echo "No @bisque-cloud mention."; exit 0
             fi
             perm="$(gh api "repos/$REPO/collaborators/$ACTOR/permission" --jq .permission)"
             case "$perm" in
               write|maintain|admin) echo "$ACTOR: $perm" ;;
               *) echo "::error::$ACTOR has '$perm' permission; @bisque-cloud needs write."; exit 1 ;;
             esac
             gh api --silent -X POST \
               "repos/$REPO/issues/comments/$COMMENT_ID/reactions" -f content=eyes
             echo "explain=true" >> "$GITHUB_OUTPUT"
         - if: steps.mention.outputs.explain == 'true'
           uses: bisque-cloud/presenter@v1
           with:
             source: pull-request
             claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
   

   If the repository takes pull requests from people you do not know, add network: deny under with:. The agent then has no shell and no internet while it reads their text, and the explainer uses system fonts.

3. Commit it to the default branch. GitHub runs comment-triggered workflows from the default branch only, so a workflow on a feature branch does nothing yet.

4. Try it. On an open pull request, comment @bisque-cloud explain this. The mention is what starts it; the rest of the comment is not read. An 👀 reaction appears within a minute; the reply with the watch link follows when the explainer is published, several minutes later. Only people with write access can start one.

Releases work the same way. Add .github/workflows/explain-releases.yml:

name: Release explainer

on:
  release:
    types: [published]

permissions:
  contents: write # append the watch link to the release notes
  id-token: write # publish as this repository, no Bisque account

jobs:
  explain:
    runs-on: ubuntu-latest
    steps:
      - uses: bisque-cloud/presenter@v1
        with:
          claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Where explainers live

A public repository's explainers are public on bisque.today/p/{owner}/{repo}, next to the GitHub path you already know: a release v1.2.0 of acme/widgets is at bisque.today/p/acme/widgets/v1-2-0. A private repository's are unlisted, reachable only by their link. Mentioning @bisque-cloud again on the same pull request, or re-running a release's workflow, replaces that explainer rather than adding a second one.

Claim your channel

Open bisque.today/p/{owner}/{repo} and choose Claim with GitHub. Sign in with the GitHub account that owns the repository, or as an admin of the organization that owns it, and the channel carries your GitHub name. Claiming is optional; explainers publish either way.

What it costs

Writing the explainer is one Claude Code run on your plan, counted like any other use of it. Narration runs on the GitHub runner, which is free on a public repository and a few minutes of Actions time on a private one. Publishing and hosting are free.

If something looks wrong

• No 👀 reaction. The workflow is not on the default branch, or the comment does not mention @bisque-cloud as a whole word: @bisque-cloudy or @bisque-cloud/presenter does not count.
• The run fails at "Narrate on this runner and publish" about id-token. The workflow's permissions: block is missing id-token: write.
• The run fails while authoring. The job log shows what the agent did, and the run's artifacts hold its working files. An expired or revoked CLAUDE_CODE_OAUTH_TOKEN fails here; make a new one with claude setup-token.

Every input is described in action.yml.