Skip to content

Add a script that sets up an organisation for the review workflow - #42

Open
cipherstash-agent wants to merge 4 commits into
mainfrom
claude/project-thread-5phrnl
Open

cipherstash-agent wants to merge 4 commits into
mainfrom
claude/project-thread-5phrnl

Conversation

@cipherstash-agent

Copy link
Copy Markdown

Requested by User · project thread

What this does

Adds scripts/setup-organisation.sh. An organisation owner runs it on their own computer to set up everything the review workflow needs:

  • The membership GitHub App. The script either creates a new app with GitHub's app manifest flow, or reuses an existing one, then has you install it on the organisation. A new app is private, has only "Members: read", and has no webhook.

  • Four organisation settings, each visible to all repositories:

    Setting Kind
    CLAUDE_REVIEW_APP_CLIENT_ID variable
    CLAUDE_REVIEW_APP_PRIVATE_KEY secret
    CLAUDE_ROUTINE_TOKEN secret
    CLAUDE_ROUTINE_TRIGGER_ID variable

Re-running is safe: a setting that is already there is kept unless you say to replace it. There are two other modes:

Private keys and tokens only reach gh secret set through stdin. They are never printed, never passed as a command argument, and never written to disk by the script. The one exception is the .pem file GitHub downloads for --rotate-key, which the script offers to delete.

The script needs only gh (with the admin:org scope) and jq, and runs on macOS's bash 3.2. It uses python3 3.7 or later, if present, for a small listener on 127.0.0.1 that catches GitHub's answer after the app is created. Without it, you paste the address the browser lands on instead, and the script checks that it came from this run.

The workflow side, which reads CLAUDE_REVIEW_APP_CLIENT_ID through the new app-client-id input, is on #41. This PR only stores the settings under those names.

Tests

  • tests/test_setup_organisation.py has 43 tests. They run the script against a stand-in gh and a stand-in browser. They cover:
    • --check, a fresh organisation, re-runs, existing apps, the paste fallback, and --rotate-key;
    • the listener on its own: HTML escaping, a wrong or non-ASCII state, and an idle connection;
    • that no key or token appears in the output or in a command's arguments.
  • A new shellcheck job lints scripts/setup-organisation.sh and .github/scripts/check-lock. shellcheck was not available locally, so this job's first run is on this PR.
  • The steps on GitHub's own pages cannot be tested automatically. The first real run on the cipherstash organisation is the live test.

Generated by Claude Code

… workflow

scripts/setup-organisation.sh creates or reuses the membership GitHub App (with
the manifest flow and a local listener, or a pasted address without python3),
installs it, and stores CLAUDE_REVIEW_APP_CLIENT_ID, CLAUDE_REVIEW_APP_PRIVATE_KEY,
CLAUDE_ROUTINE_TOKEN and CLAUDE_ROUTINE_TRIGGER_ID as organisation settings.
--check reports the settings and whether the app is installed; --rotate-key
replaces the app's private key. Keys and tokens only travel on stdin to gh.

Tested against a stand-in gh and browser; shellcheck added to the checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7rUm51nEBboQCAYhQ3
- The listener runs on macOS's python3 (3.9): postponed annotations. It
  threads requests with a timeout, so an idle browser connection cannot
  hold it up, and compares the state as bytes, so a non-ASCII one is
  refused rather than crashing it.
- Without a usable python3 (3.7 or later), or if the listener does not
  start, the script falls back to the pasted address, and checks that
  address carries this run's state.
- The script stops if GitHub's answer has no private key, and says what
  to do if storing it fails.
- Only a key file GitHub downloaded to ~/Downloads is deleted by default.
- If the installed apps cannot be listed, setup offers to keep the app.
  Reusing the app already stored offers to keep its key.
- --check reports settings not visible to all repositories.
- The manifest's url is the organisation's; no unquoted glob or tilde
  in quotes for shellcheck.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7rUm51nEBboQCAYhQ3
@cipherstash-agent cipherstash-agent self-assigned this Nov 20, 2026

Copy link
Copy Markdown
Author

integration-test: received ready request from https://github.com/cipherstash/workflows/actions/runs/44668562986/attempts/1


Generated by Claude Code

SC1007: write empty assignments as ''. SC2016 in check-lock: the backticks
are Markdown for the job summary, so the finding is disabled on that line
with the reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7rUm51nEBboQCAYhQ3
The listener now takes the code only after it has answered the callback,
so the threaded server cannot exit while the browser's "Done" page is
still being sent. The listener tests drop the closed stdin, which
communicate() rejects before Python 3.13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7rUm51nEBboQCAYhQ3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants