init and setup explain how to create the App, and stop naming ours (#125)

Both told the adopter to create the simplycubed-code GitHub App. App names
are globally unique and we hold that one, so every adopter after us got
'Name has already been taken'. The step was only performable by the account
that already owns the App.

Neither said the thing that makes the rest make sense: the App has to be
theirs, because the private key is what mints tokens against their
repository and a shared key would let its holder act on every other
installation. Without that, 'create a GitHub App' reads as busywork we
could have done for them, and the natural response is to look for ours.

init now carries the creation URL, resolved to the org form when the
repository belongs to one, the three permissions with their access levels,
webhook off and why, install visibility and why it is the step most often
missed, and where the Client ID and the download-once private key come
from. A test asserts each element, so the gate holds prose it otherwise
could not judge.

docs/setup.md says the same things in the same order, and the references
to simplycubed-code[bot] as the adopter's identity now read
<your-app-name>[bot].

The decision record in docs/decisions is left alone: it documents a past
decision rather than instructing anyone.

Closes #110
Closes #113

Author: charlesgreen

README.md

@@ -116,7 +116,7 @@ What that means for customers:
 
 Setup files are generated locally by `simplycubed init` and then merged by a human, because the runtime holds no `workflows` permission and cannot add or update workflow files on its own.
 
-The GitHub App identity is `simplycubed-code[bot]`. That bot is the single audit signal for everything the agent does.
+The GitHub App identity is your own App's `[bot]` account. That bot is the single audit signal for everything the agent does.
 
 ## Getting started
 
@@ -143,7 +143,7 @@ Then follow the [setup guide in `docs/setup.md`](docs/setup.md) to add the repos
 
 To run the loop inside your own GitHub Actions:
 
-1. Create and install the GitHub App, `simplycubed-code`.
+1. Create and install **your own** GitHub App. App names are globally unique, so it cannot be named after ours, and its private key is what mints the tokens that act on your repository.
    Repository permissions: `Contents`, `Pull requests`, and `Issues` only.
    Do not grant `Workflows`, `Administration`, `Environments`, or `Secrets`.
    That means the App cannot push changes under `.github/workflows/`: if a run needs to edit a workflow file, make that commit as a human or run the CLI locally under your own `gh` auth instead of the App token.

cmd/simplycubed/main.go

@@ -707,9 +707,30 @@ func initCmd(argv []string, stdout io.Writer) error {
 	} else {
 		fmt.Fprintf(stdout, "created labels: %s\n", strings.Join(created, ", "))
 	}
+	createURL, resolved := appCreateURL(*repoDir)
 	fmt.Fprintln(stdout, "next steps:")
-	fmt.Fprintln(stdout, "  - install the simplycubed-code GitHub App with contents, issues, and pull requests permissions only")
-	fmt.Fprintln(stdout, "  - disable the App webhook, set install visibility to Any account, and install it on the repo")
+	fmt.Fprintln(stdout, "  1. Create your OWN GitHub App. It has to be yours: its private key is what mints")
+	fmt.Fprintln(stdout, "     the tokens that act on your repository, so a shared key would let its holder act")
+	fmt.Fprintln(stdout, "     on every other installation. This is what keeps the agent inside your GitHub.")
+	fmt.Fprintln(stdout, "       "+createURL)
+	if !resolved {
+		fmt.Fprintln(stdout, "       (if this repository belongs to an organisation, use")
+		fmt.Fprintln(stdout, "        https://github.com/organizations/<org>/settings/apps/new instead)")
+	}
+	fmt.Fprintln(stdout, "     Name it anything you like; App names are globally unique, so you cannot reuse ours.")
+	fmt.Fprintln(stdout, "     Permissions, and nothing else:  Contents: Read and write")
+	fmt.Fprintln(stdout, "                                     Issues: Read and write")
+	fmt.Fprintln(stdout, "                                     Pull requests: Read and write")
+	fmt.Fprintln(stdout, "     Uncheck Active under Webhook. Actions triggers this runtime; an enabled webhook")
+	fmt.Fprintln(stdout, "     with nothing listening only generates failures.")
+	fmt.Fprintln(stdout, "     Set Any account under Where can this GitHub App be installed, if the App belongs")
+	fmt.Fprintln(stdout, "     to your personal account and the repository belongs to an organisation. An App")
+	fmt.Fprintln(stdout, "     restricted to its owner cannot be installed anywhere else, and this is the step")
+	fmt.Fprintln(stdout, "     most often missed.")
+	fmt.Fprintln(stdout, "  2. Generate a private key on the App settings page and keep the download. GitHub")
+	fmt.Fprintln(stdout, "     shows it once. Note the Client ID there too, the Iv23 string.")
+	fmt.Fprintln(stdout, "  3. Install the App on this repository, from Install App on the same page.")
+	fmt.Fprintln(stdout, "     Reference: https://docs.github.com/apps/creating-github-apps")
 	fmt.Fprintln(stdout, "  - write the real gate in .github/simplycubed.yml")
 	fmt.Fprintln(stdout, "  - verify that gate is green on your main branch")
 	fmt.Fprintln(stdout, "  - add two repository VARIABLES, under Settings > Secrets and variables > Actions > Variables:")
@@ -727,6 +748,29 @@ func initCmd(argv []string, stdout io.Writer) error {
 	return nil
 }
 
+// appCreateURL returns the GitHub form for creating an App, which differs by
+// account type. Best effort: init must still work when gh cannot answer, so a
+// failure returns the personal form and a note rather than an error.
+func appCreateURL(repoDir string) (string, bool) {
+	out, err := exec.Command("gh", "repo", "view", "--json", "owner", "--jq", ".owner.login").Output()
+	_ = repoDir
+	if err != nil {
+		return "https://github.com/settings/apps/new", false
+	}
+	owner := strings.TrimSpace(string(out))
+	if owner == "" {
+		return "https://github.com/settings/apps/new", false
+	}
+	kind, err := exec.Command("gh", "api", "users/"+owner, "--jq", ".type").Output()
+	if err != nil {
+		return "https://github.com/settings/apps/new", false
+	}
+	if strings.TrimSpace(string(kind)) == "Organization" {
+		return "https://github.com/organizations/" + owner + "/settings/apps/new", true
+	}
+	return "https://github.com/settings/apps/new", true
+}
+
 func writeStarterConfig(path string) (bool, error) {
 	return writeStarterFile(path, starterConfig)
 }

cmd/simplycubed/main_test.go

@@ -126,8 +126,19 @@ exit 0
 	for _, want := range []string{
 		"wrote " + configPath,
 		"created labels: sc:go, sc:queued, sc:working, sc:review, sc:blocked, sc:done",
-		"install the simplycubed-code GitHub App with contents, issues, and pull requests permissions only",
-		"disable the App webhook, set install visibility to Any account, and install it on the repo",
+		// The App has to be the adopter's own, and the output has to say why.
+		// Without that, "create a GitHub App" reads as busywork we could have
+		// done for them, and the natural next move is to look for ours.
+		"Create your OWN GitHub App",
+		"its private key is what mints",
+		"App names are globally unique, so you cannot reuse ours",
+		"Contents: Read and write",
+		"Issues: Read and write",
+		"Pull requests: Read and write",
+		"Uncheck Active under Webhook",
+		"Set Any account under Where can this GitHub App be installed",
+		"GitHub\n     shows it once",
+		"https://docs.github.com/apps/creating-github-apps",
 		"write the real gate in .github/simplycubed.yml",
 		"verify that gate is green on your main branch",
 		// Naming the section is the point: two of the four go under Variables

docs/faq.md

@@ -15,7 +15,7 @@ You can use SimplyCubed Code two ways:
   runs your gate, and opens or updates a pull request as you;
 - or through the reusable workflow that runs inside your own GitHub Actions, as
   described in the README's install section, which now mints a per-job GitHub
-  App installation token for `simplycubed-code[bot]`.
+  App installation token for your own App's `[bot]` identity.
 
 The GitHub App is configured with only `contents`, `pull requests`, and
 `issues`, and the reusable workflow proves that scope at runtime by expecting an

docs/setup.md

@@ -71,24 +71,47 @@ simplycubed run owner/repo#N --repo-dir .
 4. Create and install the GitHub App identity, then add the required repository
 settings.
 
-Create the `simplycubed-code` GitHub App with `Contents`, `Issues`, and `Pull
-requests` permissions only, disable the webhook, set install visibility to `Any
-account`, and install it on the repository.
-
-Then add these repository settings:
+**The App has to be your own.** Its private key is what mints the tokens that act
+on your repository, so a shared key would let whoever holds it act on every other
+installation of that App. That is why there is no App to install *from us*, and
+it is what makes "runs in your GitHub, not ours" true rather than a slogan.
+
+Create it at [github.com/settings/apps/new](https://github.com/settings/apps/new),
+or at `https://github.com/organizations/<org>/settings/apps/new` if the repository
+belongs to an organisation. GitHub's own reference is
+[Creating GitHub Apps](https://docs.github.com/apps/creating-github-apps).
+
+- **Name:** anything you like. App names are globally unique, so you cannot reuse
+  ours, and your bot will be `<your-app-name>[bot]`.
+- **Permissions**, and nothing else: `Contents: Read and write`,
+  `Issues: Read and write`, `Pull requests: Read and write`.
+- **Webhook:** uncheck `Active`. Actions triggers this runtime, so an enabled
+  webhook with nothing listening only generates failures.
+- **Where can this GitHub App be installed:** `Any account`, if the App belongs to
+  your personal account and the repository belongs to an organisation. An App
+  restricted to its owner cannot be installed anywhere else. This is the step most
+  often missed.
+
+Generate a private key on the App settings page and keep the download; GitHub
+shows it once. Note the Client ID there too, the `Iv23` string. Then install the
+App on the repository from `Install App`.
+
+Then add these repository settings. **Variables and Secrets are different tabs**
+under Settings > Secrets and variables > Actions, and a value filed under the
+wrong one reads back as empty rather than failing:
 
 - Variable: `SIMPLYCUBED_GH_APP_CLIENT_ID`, the App Client ID, the `Iv23` string on the App settings page
 - Secret: `SIMPLYCUBED_GH_APP_PRIVATE_KEY`
 - Variable: `SIMPLYCUBED_AZURE_OPENAI_ENDPOINT`
 - Secret: `SIMPLYCUBED_AZURE_OPENAI_API_KEY`
 
-The Actions runtime authenticates as the `simplycubed-code` GitHub App, so the
-App ID and private key are required. Store the private key as the full PEM
-contents, including the `-----BEGIN` and `-----END` lines.
+The Actions runtime authenticates as your App, so the Client ID and private key
+are both required. Store the private key as the full PEM contents, including the
+`-----BEGIN` and `-----END` lines.
 
 Each job mints its own installation token for that repository, so the agent
-authors commits, pull requests, and comments as `simplycubed-code[bot]`, and
-its pull requests receive their own CI runs. A personal access token is not an
+authors commits, pull requests, and comments as `<your-app-name>[bot]`, and its
+pull requests receive their own CI runs. A personal access token is not an
 alternative: the reusable workflow accepts App credentials only.
 
 5. Commit the generated config and workflow files in the target repository, open
@@ -153,7 +176,7 @@ flowchart TB
         A2["repository secrets<br/>SIMPLYCUBED_AZURE_OPENAI_API_KEY<br/>SIMPLYCUBED_GH_APP_PRIVATE_KEY"]
         A3["per-job installation token<br/>contents, issues, pull requests"]
         A4["simplycubed run / address"]
-        A5["commits and PR authored by<br/>simplycubed-code[bot]"]
+        A5["commits and PR authored by<br/>your-app-name[bot]"]
         A2 --> A3
         A1 --> A4
         A2 --> A4