Skip to content

docs(selfhost): close first-run onboarding gaps for admin access and GitHub App setup #2542

Description

@JSONbored

Parent: #1936

Problem

A few first-run operator experience gaps surfaced during a portability review, distinct from the broader image-first onboarding work already tracked in #1938:

  • The environment variable that grants control-panel "operator" access is not documented anywhere and defaults to nobody having access — a first-time operator who signs into their own instance's dashboard gets silently zero privileges with no explanation.
  • A working one-click GitHub App setup flow exists in the codebase but isn't mentioned in the self-hosting docs at all; the docs instead describe manual GitHub App creation, and the manually-documented recommended permission set does not match what the one-click flow actually requests — an operator who reads the docs and creates their App manually with the documented (narrower) permissions could unexpectedly break auto-merge without any indication why.
  • A handful of other environment variables the app genuinely reads at runtime (a webhook body-size guard, the visual-review browser endpoint, MCP read/write allowlists, AI spend-budget controls) are absent from the example env file, forcing an operator to grep source to discover them.

Requirements

  • Document the admin-access environment variable clearly in both .env.example and the relevant self-hosting doc page, including what happens when it's unset (fail-closed, no operator access) so it isn't mistaken for a bug.
  • Either document the one-click GitHub App setup flow as the recommended path, or reconcile the documented manual-permission set with what the flow actually requests — pick one source of truth and make the docs match the code.
  • Add the identified missing environment variables to .env.example with a short description each.

Deliverables

  • .env.example and doc updates for the admin-access variable.
  • Doc + code reconciliation for the GitHub App permission set (either documented one-click flow, or corrected manual instructions).
  • .env.example entries for the other identified missing variables.

Acceptance criteria

  • A first-time operator can find, in one documented place, how to grant themselves control-panel access.
  • The documented GitHub App permissions match what the app actually needs for its default-enabled features.
  • No currently-functional environment variable is undiscoverable without reading source.

Expected outcome

A new operator can complete first-time setup end to end using only the published documentation, without needing to read application source to find working configuration.

Metadata

Metadata

Assignees

Labels

maintainer-onlyOwner-only work — yields no Gittensor points.roadmapOn the Wave-2 agent-layer roadmap board (project 9)

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions