Onboard a repo

Onboarding creates the control-plane registration that links a GitHub repo to a GitHub App installation and, optionally, tenant, account, and project refs. Without that registration, deploy authorization or source fetch cannot succeed for the repo. In the self-service path, pass the served app ref with --app-ref, such as app:<repo-name>. The CLI stores that value as identity.project_ref because the manifest field has that name, and uses the same value for route, version, publish, and optional custom-CI deploy requests.

map onboard --installation-ref <installation-ref> <owner/repo> --repo-dir .

If you do not administer the GitHub organization or tenant, confirm the repository grant, installation ref, and tenant/account/project refs with the person following Administer Forge before running this command.

Before you run it

Confirm these inputs before onboarding:

Input	Why it matters
GitHub App grant	The repo must be granted to the Forge GitHub App shown by the customer setup link.
Installation ref	The control plane uses this ref to authorize source fetch for the repo.
Tenant and account refs	These attach the app to the intended customer boundary when your account uses them.
App/project ref	Defaults to app:<repo-name> when omitted. In the self-service path, pass the served app ref with --app-ref so onboarding, route, version, publish, and optional custom-CI deploy identity stay aligned.
Repo checkout	--repo-dir . lets the CLI write starter files into the checkout.
Deploy trigger decision	Built-in webhook deploys need no repo workflow. Use --with-ci-workflow only when the repo needs custom CI to request deploys.

What it does

When you run map onboard with --installation-ref <installation-ref>, <owner/repo>, and --repo-dir <checkout>, the CLI does these things:

1. Sends an authenticated request to /v1/map-control/onboard.
2. Records the repo registration for the GitHub App installation and optional tenant, account, and project refs.
3. Writes a starter mithran.yaml only if --repo-dir is set and the file does not already exist.
4. Writes .github/workflows/map-deploy.yml only when --with-ci-workflow is set.
5. When custom CI is requested, tries to create or update the non-secret GitHub repo Variables it can derive from the onboarding inputs.

The JSON output uses schema_version: map.onboard.v1 and includes the repo, control-plane response, whether the custom-CI workflow was requested, any local file paths written, the repo-variable result, and the recommended next action.

When onboarding writes a starter manifest for --repo-dir ., successful text output looks like this:

onboarded <owner/repo> (repo registration recorded).
app identity: app:<repo-name> (stored as identity.project_ref; used for deploy routing, versions, and publish).
wrote ./mithran.yaml
next: commit + push mithran.yaml, then push a release/* ref (or tag) — the webhook deploys (no repo workflow needed).

The first line is the control-plane registration result. wrote ... lines are local file scaffolds; review and commit those files before relying on them in a release. With --json, inspect these fields:

Field	What to check
ok	true means the CLI finished successfully.
repo	The onboarded GitHub repo, in owner/repo form.
onboard.status	onboarded means Forge accepted the registration.
onboard.repository_ref	github://<owner>/<repo> for the repo you intended.
onboard.installation_ref	The GitHub App installation ref used for source fetch.
project_ref and app_ref	The resolved app/project ref. These values match; app_ref is included so the deploy-routing identity is explicit.
identity_note	Reminder that the resolved project ref is also the self-service app identity used by deploy routing, version, and publish surfaces.
onboard.tenant_ref, onboard.account_ref, onboard.project_ref	The tenant/account refs and resolved project/app ref recorded by the control plane when supplied.
manifest_written	Local mithran.yaml path when onboarding wrote a starter; null when the file already existed or no --repo-dir was supplied.
workflow_written	Local custom-CI workflow path only when --with-ci-workflow wrote one.
variables	Best-effort GitHub repo Variable results for the optional custom-CI workflow. This can report set: false or per-variable failures without invalidating the repo registration.
next	The next action recommended for the selected deploy path.

The starter is a map.mithran/v1 MithranApp HTTP skeleton. It uses the repo name as metadata.app_id, writes the resolved --app-ref or --project-ref value to identity.project_ref, and starts with runtime: nodejs22 plus startup.command: npm start. For self-service apps, keep identity.project_ref app-ref-shaped, such as app:<repo-name>, so deploy, version, publish, and hostname expectations stay aligned.

Starter shape:

mithran.yaml

apiVersion: map.mithran/v1
kind: MithranApp
metadata:
  app_id: <repo-name>
  name: <repo-name>
identity:
  project_ref: <project-ref>
capabilities:
  - kind: http
    route: /
    runtime: nodejs22
    startup:
      command: npm start

map onboard never overwrites an existing mithran.yaml. If your repo already has one, review and commit that file through the repo's normal review path.

Built-in deploys use GitHub App webhooks. A map-deploy.yml workflow is only needed when your team wants deploy dispatch from GitHub Actions or another custom CI path; add --with-ci-workflow during onboarding to scaffold it.

What it does not do

• It does not install or grant the GitHub App in GitHub.
• It does not build, deploy, promote, or publish the app.
• It does not write .github/workflows/map-deploy.yml unless --with-ci-workflow is set.
• It does not overwrite an existing mithran.yaml.
• It does not store a Forge deploy secret in the repo.

Default webhook path

Use the default path for most repos:

map onboard --installation-ref <installation-ref> <owner/repo> --repo-dir .

The default path does not write a repo workflow and does not change GitHub Actions configuration. Deploys start from GitHub App webhooks when you push a built-in deploy ref:

What you push	GitHub ref Forge evaluates	Default app environment
main branch	refs/heads/main	preview
release/* branch	refs/heads/release/*	production
release/* tag	refs/tags/release/*	production

The built-in webhook path only creates deploy candidates for these refs. Manifest app_env entries can include reviewed auto_deploy_refs that refine which app environment receives those candidates after Forge snapshots the manifest. They do not make arbitrary refs deployable through the built-in webhook path. See Deploy.

If a pushed ref does not match the built-in policy, Forge acknowledges the webhook and does not create a deploy.

Optional custom-CI path

Use this only when the repo needs GitHub Actions or another CI system to request deploys directly:

map onboard --installation-ref <installation-ref> <owner/repo> --repo-dir . --with-ci-workflow

With --with-ci-workflow, onboarding writes .github/workflows/map-deploy.yml. The generated workflow requests a GitHub Actions OIDC token, exchanges it with Mithran auth for a short-lived map-control token, and posts a deploy request to /v1/map-control/deploy/request.

Use this path only when GitHub Actions or another CI system must own deploy dispatch. The built-in webhook path remains available through the GitHub App grant; adding the workflow does not disable webhooks.

The workflow does not use a stored Forge deploy secret. It reads non-secret repo Variables:

Variable	Set by onboarding when available	Purpose
MAP_INSTALLATION_REF	yes	GitHub App installation ref for source fetch.
MAP_APP_REF	yes	Resolved project/app ref passed as app_ref to the deploy request.
MAP_TENANT_REF	when --tenant-ref is passed	Tenant ref.
MAP_ACCOUNT_REF	when --account-ref is passed	Account ref.
MAP_CONTROL_ENDPOINT	no	Required control-plane endpoint for custom-CI deploy requests. Set it from the production account setup values.
MAP_AUTH_ENDPOINT	no	Required auth endpoint for the GitHub OIDC token exchange. Set it from the production account setup values.
MAP_OIDC_AUDIENCE	no	OIDC audience override when the repo should not use the workflow default, map-control.

Setting repo Variables is best effort. The CLI can derive MAP_INSTALLATION_REF, MAP_APP_REF, and optional tenant/account refs from the onboarding command. Set MAP_CONTROL_ENDPOINT and MAP_AUTH_ENDPOINT from the customer account setup values. If the CLI cannot use a GitHub token to write variables, it reports the names to set manually. The onboarding registration can still succeed.

The generated workflow triggers on release/** branches, tags matching the workflow's v[0-9]+.[0-9]+.[0-9]+ filter, and manual dispatch. Push triggers target the production app environment. Manual dispatch uses the workflow env input. That trigger policy is owned by the checked-in workflow and is separate from the built-in webhook policy.

For manual workflow dispatch, the workflow env input selects the app environment in the deploy request. It does not change the customer account context. For custom CI in a customer account, set MAP_CONTROL_ENDPOINT and MAP_AUTH_ENDPOINT from the account setup values. The generated workflow has no endpoint or account-context defaults; it fails clearly when required Variables are missing.

For the built-in webhook path, refs/tags/release/* is a production trigger; the generated workflow's v[0-9]+.[0-9]+.[0-9]+ tag filter does not apply to webhook deploys. For the optional custom-CI path, that tag filter belongs to the checked-in workflow because the workflow owns its own trigger policy.

Review the app ID, project/app ref, runtime, startup command, exposure, and app-environment policy, then commit the manifest:

git add mithran.yaml
git commit -m "Onboard to Forge"
git push

If you used --with-ci-workflow, also review and commit the generated workflow:

git add .github/workflows/map-deploy.yml
git commit -m "Add Forge deploy workflow"
git push

Useful flags

• --repo-dir <path>: where to write starter files. Use . from inside a checkout.
• --installation-ref <ref>: required. Use the GitHub App installation ref for the customer account and repo owner.
• --tenant-ref, --account-ref: tenant and account refs when your account uses them.
• --app-ref <ref>: served app ref for the self-service path. It is a visible alias for --project-ref.
• --project-ref <ref>: underlying project/app ref flag. Defaults to app:<repo-name>.
• --with-ci-workflow: also scaffold the optional custom-CI workflow and try to set the repo Variables the CLI can derive from onboarding inputs.
• --workflow <name>: workflow filename used with --with-ci-workflow; defaults to map-deploy.yml.

See the CLI reference for the full list.

Evidence to keep

Keep these items with the app onboarding record:

• the map onboard command and output;
• the GitHub App installation ref;
• the tenant, account, and project/app refs used for the app;
• the committed mithran.yaml diff;
• the custom-CI workflow diff when --with-ci-workflow was used;
• map doctor --app <owner/repo> output after onboarding.

If onboarding returns an API error

Onboarding can return API errors for invalid input, a missing or mismatched GitHub App grant, conflicting onboarding state, or a control-plane condition the CLI cannot correct.

Re-check the repo slug, installation ref, setup context, tenant/account refs, project/app ref, and GitHub App grant. Re-run onboarding only after one of those inputs or grants changes. Background on the install flow is in Connect GitHub.

If onboarding returns an unexpected conflict or a 5xx response, keep the full redacted response body with the onboarding evidence and use Support and escalation.

Check readiness after onboarding

map doctor --app <owner/repo>

doctor --app adds app-specific readiness and recent-deploy diagnostics to the saved endpoint checks. It does not list the full onboarding record directly; keep the map onboard output as the repo registration record.

Then deploy through the path you chose:

Path	Next step
Built-in webhook	Push the main branch, a release/* branch, or a release/* tag.
Optional custom CI	Push a workflow trigger ref or run workflow_dispatch.
Direct operator request	Run map deploy --repo <owner/repo> --env <app-env> --ref <git-ref> --installation-ref <installation-ref>, or use --sha <40-hex-sha> instead of --ref.

If onboarding or deploy auth fails, start with Webhook deploy does not start and Custom-CI deploy auth fails.

Admin review checklist

Before the first customer-visible deploy, confirm:

• the repo is granted to the Forge GitHub App shown by the customer setup link;
• the installation ref belongs to the same GitHub account or organization as the repo;
• tenant, account, and project/app refs match the customer account;
• mithran.yaml has the reviewed app ID, project/app ref, runtime, startup command, exposure, and app-environment policy;
• metadata.app_id and served app ref match the intended hostname;
• public_edge.exposure matches the approved access model;
• reviewed app_env metadata and any auto_deploy_refs match the intended app environments;
• custom-CI workflow changes are reviewed only when the repo needs that path;
• map doctor --app <owner/repo> has no blocking failures before release deploys.