nebuko init — App-aware setup

nebuko init prepares a repository for Nebuko. When the Nebuko GitHub App is installed on the target repository it configures everything without asking for a Personal Access Token; otherwise it falls back to the existing PAT flow.

Quick start

Prerequisites:

Admin on the target repository — init writes a workflow file, a repository variable, and (in PAT mode) secrets.
The gh CLI, authenticated — init performs every GitHub operation through your own gh session. gh auth refresh -s workflow is required because the generated file lives under .github/workflows/.
The Nebuko App — install it from https://github.com/apps/nebuko/installations/new and grant it the target repository. Installing the App is what makes the no-PAT path available.

Then, from the repository you want to set up:

nebuko init

Happy path — a fresh repository with the App installed:

$ nebuko init
Target repository (owner/name): acme/widgets
LLM provider
  1) openrouter
  ...
OPENROUTER_API_KEY: ****
Caller workflow: created (.github/workflows/nebuko-caller.yaml)
Nebuko App detected: the workflow mints its token from the OIDC broker.
Next steps
1. Review and merge the pull request: https://github.com/acme/widgets/pull/7

There is no GH_PAT prompt: the App supplies the token.

Non-interactive use (CI, scripts) takes every answer from flags and NEBUKO_SECRET_<NAME> environment variables:

NEBUKO_SECRET_OPENROUTER_API_KEY=... \
  nebuko init --repo acme/widgets --provider openrouter --non-interactive

What `nebuko init` creates

Artifact	Where	Purpose
Agent configuration	`.nebuko/agents/agent-config.yaml` (in the PR)	Provider, models and agent roles.
Caller workflow	`.github/workflows/nebuko-caller.yaml`	The entrypoint GitHub Actions runs.
Secrets	repo or org settings	The provider key, plus `GH_PAT` in PAT mode only.

The generated caller workflow carries the contract from the caller-workflow spec:

on: issue_comment with types: [created, edited] — comments start runs.
An author gate — only OWNER, MEMBER and COLLABORATOR comment authors trigger a run, plus comments authored by nebuko[bot], so the agent’s own continuation comments can start the next step. The reusable workflow only acts on bot comments that carry a continuation marker, so the agent never answers itself.
permissions: id-token: write — the job may request a GitHub OIDC token, which is what the broker exchange needs.
A reference to ${{ vars.NEBUKO_BROKER_URL }} — the broker endpoint is read from the repository variable when one is set, and otherwise falls back to the published broker baked into the workflow. init does not write the variable; pointing at your own broker still needs no workflow edit (set the variable by hand, or re-run init with --broker-url if you also want the legacy variable write).

The first line is the marker # generated by nebuko init. init uses it to recognise its own output on later runs.

How it works

Detection. init calls the GitHub repository-installation endpoint for owner/repo. A 200 means the Nebuko App is installed on that repository; a 404 means it is not. The answer selects the mode for the rest of the run.
No App? guidance first. When the App is not installed and you did not pass --pat, init stops before any secret prompt and prints the App install link (https://github.com/apps/nebuko/installations/new) plus the --pat escape hatch. Install the App and re-run, or pass --pat.
Caller workflow. The workflow is rendered from a packaged template and written to .github/workflows/nebuko-caller.yaml.

At run time the generated workflow requests an OIDC token from GitHub (id-token: write), posts it to the broker named by ${{ vars.NEBUKO_BROKER_URL }}, and receives a short-lived App installation token in exchange. That installation token — not a long-lived PAT — is what the engine uses to push branches, open pull requests and post comments. The token expires with the job, so there is no credential to rotate.

PAT mode (fallback)

PAT mode is selected when you pass --pat (alias --assume-pat). A 404 from the detection probe no longer silently selects PAT mode: init stops with the App install link so the default path stays the App.

In PAT mode init prompts for GH_PAT (skipped, with a note, if it is already stored) and prints the fine-grained-token creation link. The PAT needs Contents, Pull requests and Issues read/write on the target repository. It is stored as a repository (or organization) secret and used by the engine for the same operations the installation token covers in App mode.

The PAT is never written to a file, never printed, and never included in the generated pull request.

Re-running `nebuko init`

init is idempotent: it compares what it would write with what is on disk.

Situation	Result
The file does not exist	`CREATED` — written.
The file is byte-identical to the render	`UNCHANGED` — left alone (not rewritten).
The file differs and carries the `# generated by nebuko init` marker	`UPDATED` — rewritten, with a notice printed.
The file differs and carries no marker	`REFUSED` — left untouched.

REFUSED is the important one: a workflow that init did not generate is somebody’s hand-written work, so it is never overwritten silently. Move or rename the file if you want init to take over that path.

The repository variable is an upsert, so re-running simply refreshes the value. Secrets already stored are reported and skipped unless you pass --force.

--dry-run prints the plan — the rendered workflow and the variable it would write — without touching the filesystem or the repository settings. It is the safe way to check what a re-run would change.

Troubleshooting

The App is installed but init still asks for a PAT. Detection only sees installations the authenticated gh user can query, and it matches the App slug nebuko. Confirm the App is installed on this repository (not just the organization) and that gh auth status shows the account that installed it. Use --assume-app to proceed offline.

The workflow runs but the broker step fails. Check that the NEBUKO_BROKER_URL repository variable, if you set one, is a URL. The workflow falls back to the published broker when the variable is absent, so a missing variable is not an error by itself — a malformed one is. Fix it by hand under Settings → Secrets and variables → Actions → Variables.

The App is not installed and init stops with an install link. Install the App from the printed URL and re-run, or force the PAT fallback with --pat (alias of --assume-pat).

init reports REFUSED for the caller workflow. A file already exists at .github/workflows/nebuko-caller.yaml without the # generated by nebuko init marker. It was not produced by init, so it is left alone. Rename or remove it and re-run.

No network / air-gapped. --assume-app and --pat skip the installation probe and force the mode; --broker-url is a legacy override that no longer writes a repo variable.