Skip to content

setup.md tells every adopter to create an App with a name only we can have #110

Description

@charlesgreen

The problem

docs/setup.md:74 and the simplycubed init next-steps output both tell the adopter:

Create the simplycubed-code GitHub App with Contents, Issues, and Pull requests permissions only

GitHub App names are globally unique, and that one is already registered:

$ gh api /apps/simplycubed-code
{"name":"simplycubed-code","owner":"simplycubed","slug":"simplycubed-code",...}

Every adopter who follows the instruction gets Name has already been taken. The step is only performable by the account that already owns the App.

Why it is not obvious

The setup flow reads as though the App is something the adopter installs from us. It isn't: the private key is what mints installation tokens, so each adopter must own their own App. That is the right design and it is what makes "runs in your GitHub, not ours" true, but the docs never say why the App has to be theirs, so the natural reading is that they should reproduce ours exactly, name included.

Sites

  • docs/setup.md:74
  • cmd/simplycubed/main.go:651 — the init next-steps line
  • cmd/simplycubed/main_test.go:129 — asserts that string, so it changes with the fix

Suggested shape

Tell the adopter to create an App under their own account or org with a name of their choosing, and say plainly that the private key is theirs alone and must never be shared, because a PEM authenticates as the App globally rather than per-installation.

Worth stating the two follow-on consequences in the same place, since both surprise people: their bot will be <their-app-name>[bot], not simplycubed-code[bot], and an App created under a personal account needs "Any account" visibility to be installable on an org they own.

Related: #111 and #112, the two behaviours that assume the vendor's App name.

Acceptance

  • No instruction anywhere tells an adopter to create an App named simplycubed-code. Grep docs/ and cmd/ for the literal.
  • cmd/simplycubed/main.go:651 names no specific App name, and cmd/simplycubed/main_test.go:129 asserts the new string. That assertion is the gate's only hold on this change, so it must be updated rather than deleted.
  • The output and docs/setup.md both state, in one sentence, that the App must be the adopter's own and the private key is never shared. That is the fact whose absence causes the wrong reading.
  • The output and docs/setup.md agree. They are the same instruction in two places and drift is what produced this issue.
  • make check green

Note for whoever runs this

Most of this is prose, and make check cannot judge prose. The test assertion above is the only mechanical anchor, so the diff needs a human read for tone and accuracy rather than a green gate.

Run this together with #113, which rewrites the same init output and the same docs/setup.md section. Splitting them across two runs guarantees a conflict.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions