Skip to content

Latest commit

 

History

History
100 lines (78 loc) · 10 KB

installation.md

File metadata and controls

100 lines (78 loc) · 10 KB

Repository installation and CLI provisioning

This release uses the CLI once for credential provisioning. Install/select the GitHub App, protect the default branch, create and merge the workflow/configuration setup PR, then connect ChatGPT using the commands below. Ongoing automatic reviews and merges run on GitHub Actions without a running CLI or personal machine. With browser onboarding disabled, the GitHub App installation callback at /dashboard redirects to the canonical public CLI setup landing page; callback query values never authorize configuration. Browser OAuth is deferred; WEB_ENABLED and OPENAI_HOSTED_INFERENCE_AUTHORIZED remain false until the separate website client is provisioned.

The hosted backend and CLI default is https://codexbot.appsolves.workers.dev. Self-hosted operators supply their own --backend and source pin. Existing ChatGPT connections must follow the origin cutover and reconnect procedure before using this new origin; they are not transferable ciphertext.

Setup permissions and supported plans

The full browser manifest requests Workflows, Administration and Environments write for workflow files, protected Environments and encrypted Environment secrets respectively. The public App already has these grants according to live metadata; every installation is checked independently. A missing grant requires an official permission upgrade and installer consent. Review-only/manual installations may retain a smaller permission profile. Otherwise use the first-class manual workflow below, or add --setup-as-user with a temporary single-repository administrator credential granting Contents/Pull requests/Workflows write. It creates the same reviewed setup PR under your own identity; no automatic elevation or retained user token is used.

Before creating a setup PR or connecting credentials, the CLI probes Environment availability using live repository-admin access. Public repositories can use Environments on Free; private repositories need Pro, Team or Enterprise support and appropriate permissions. A 403/404 cannot alone distinguish an unsupported plan from an insufficient token; the error states both requirements. Outages/rate limits are reported separately. See GitHub's Environment availability. No repository-secret downgrade exists.

npm ci --ignore-scripts
npm run cli -- setup --repository OWNER/REPO --backend https://codexbot.appsolves.workers.dev \
  --source YOUR-ORG/codexbot --ref FULL_COMMIT_SHA --setup-as-user

Omit --setup-as-user only when the App has Workflows write. Backend setup checks live admin/installation/repository scope, source pin, permission and Origin; bearer authentication has no ambient cookies or permissive CORS. Both setup files appear atomically in one commit on codexbot/setup. Existing default files are never overwritten. Repeated setup verifies exact existing branch content, its two-file diff and PR head/base before returning the existing PR. Divergent/legacy partial setup branches require manual inspection; no force update occurs.

Manual workflow

Create .codexbot.yml from the example; allow only intended GitHub users. For initial acceptance set review.auto_approve and review.request_changes false, and keep merge.enabled false. Add this file through a reviewed PR on the default branch:

name: CodexBot
run-name: CodexBot ${{ inputs.request_id }} ${{ inputs.dispatch_attempt }}
on:
  workflow_dispatch:
    inputs:
      request_id: { required: true, type: string }
      credential_owner: { required: true, type: string }
      installation_id: { required: true, type: string }
      dispatch_attempt: { required: true, type: string }
      credential_check_only: { required: false, type: boolean, default: false }
permissions: {}
concurrency:
  group: codexbot-credentials
  cancel-in-progress: false
jobs:
  credential-scope:
    runs-on: ubuntu-latest
    timeout-minutes: 1
    permissions: {}
    steps:
      - name: Reject credentials outside protected Environments
        shell: bash
        env:
          CODEXBOT_SHARED_CREDENTIAL_PRESENT: ${{ secrets.CODEXBOT_VAULT_KEY != '' || secrets.CODEXBOT_API_KEY != '' }}
        run: |
          node --input-type=module <<'JS'
          if (process.env.CODEXBOT_SHARED_CREDENTIAL_PRESENT !== 'false') {
            console.error(JSON.stringify({event: 'review_failed', stage: 'environment', code: 'non_environment_credentials_forbidden'}));
            process.exitCode = 1;
          }
          JS
  review:
    needs: [credential-scope]
    permissions:
      contents: read
      id-token: write
    uses: YOUR-ORG/codexbot/.github/workflows/review.yml@FULL_COMMIT_SHA
    secrets:
      CODEXBOT_VAULT_KEY: ${{ secrets.CODEXBOT_VAULT_KEY }}
      CODEXBOT_API_KEY: ${{ secrets.CODEXBOT_API_KEY }}
    with:
      request_id: ${{ inputs.request_id }}
      credential_owner: ${{ inputs.credential_owner }}
      installation_id: ${{ inputs.installation_id }}
      backend: https://codexbot.appsolves.workers.dev
      credential_check_only: ${{ inputs.credential_check_only }}

Use the exact filename .github/workflows/codexbot.yml and the backend's trusted immutable source pin. Do not add secrets: inherit, fork-head checkout, repository hooks or PR-controlled commands. The reusable workflow resolves its own source from GitHub's TLS-delivered workload identity; the backend independently verifies the signed claims/run before releasing anything.

Use the two named secret references, not literal empty grants. The credential-scope job must have no Environment and must succeed before the reusable workflow starts. It passes only a boolean to its process and rejects nonempty repository/organization credentials under either name, preventing fallback to shared keys. Do not remove this guard, add always() to its dependent job or use blanket inheritance. Exactly one credential must exist in the owning protected Environment. The credential-only diagnostic checks availability and a read-only administrator workload, without building an image, acquiring a session or running Codex. See credential semantics and existing-caller migration.

Credentials

Protect the default branch before connecting. New codexbot-INSTALLATION_ID-NUMERIC_USER_ID and codexbot-publish-INSTALLATION_ID Environments use a default-branch-only custom deployment policy. The installation namespace isolates both API keys and OAuth vault keys across independent Apps/reinstalls. Existing reviewers/timers are preserved. Unrestricted Environments and custom policies allowing other branches/tags are rejected. Existing protected-branch policies require an actually protected default branch: GitHub otherwise permits every branch when no protected branches exist. Private Free repositories are unsupported.

npm run cli -- connect --repository OWNER/REPO --backend https://codexbot.appsolves.workers.dev
# Or, after securely setting CODEXBOT_API_KEY in the local process:
npm run cli -- connect-api-key --repository OWNER/REPO --backend https://codexbot.appsolves.workers.dev

ChatGPT connection checks the backend deployment gate before sign-in. Use your own eligible account/workspace; manual auth.json export is unnecessary and not supported. API keys go to GitHub through gh stdin; never the Worker. Set credentials.mode appropriately and remove the other mode's secret. API billing and ChatGPT allowance never fall back into one another.

Credential provisioning currently requires repository administrator access. Each authorized human needs their own Environment and credential; ordinary contributors need administrator assistance. Fine-grained provisioning access needs Administration write for Environment creation and Environments write for secrets. Review-only runtime tokens never have those permissions. GitHub Environment Secrets are available to workflows authorized to enter that Environment, not cryptographically restricted to this one workflow: trusted workflow writers/admins remain inside the boundary.

Disconnect retrieves/revokes the latest ChatGPT session, deletes the encrypted record and both named credential secrets for your Environment, and rotates the local vault key. Revoke removed API keys in OpenAI settings separately; a user API key cannot revoke itself through the administrative management API. Session removal remains available even if Environment support disappears. GitHub secret deletion can still require restored feature/permission access.

Verify before enabling privileges

Run advisory acceptance, then independently enable approval if appropriate. Merge needs a separate whitelist, protected branch, either explicit --merge or owner-opted-in automatic merge-on-approval, and the operator's deployment acceptance gate. Choose Fully Autonomous (0 humans) or Human-in-the-Loop (1–6); stricter GitHub human requirements remain enforced. Pending CI also requires the App-bound required guard and optional merge permissions. Ready PRs use a native exact-head merge. Unknown/conflicting/queue states are manual-only; the bot never bypasses protections.

For unattended reviews from authorized contributors without provider accounts, connect the administrator's own repository credential with --allow-automatic-reviews, then opt into credentials.automatic_reviewer: YOUR_LOGIN and review.auto_review: true through protected configuration. The event actor still passes the repository review policy. Never copy another repository's vault, refresh token or Environment secrets. See explicit credential consent.

The broker supports both GitHub default OIDC subject formats: legacy repository names and the immutable OWNER@OWNER_ID/REPO@REPOSITORY_ID format used for new repositories. Both require the exact protected Environment, signed numeric tenant claims and immutable reusable workflow. Custom subject templates are unsupported. See GitHub OIDC reference.