Administer Forge¶
Use this path when you are responsible for a customer account, GitHub organization, repository grants, app access, or security review.
Core Concepts¶
For the full terminology list, see the Glossary.
| Term | What it means for administration |
|---|---|
| Tenant | The customer boundary Forge uses when authorizing app and deploy activity. |
| Account | The business account or workspace under the tenant. |
| Project | The grouping that ties an app to a repo or product area. |
| App | A Forge-deployed service with a mithran.yaml, runtime, and route. |
| GitHub organization | The GitHub owner where repos live and where the Forge GitHub App is installed. |
| Repository grant | The set of repos the Forge GitHub App can read for source fetch. |
| Onboarding | The map onboard registration that binds a repo to tenant, account, project, and app refs. |
Responsibility split¶
Forge adoption usually crosses three roles:
| Role | Typical responsibility |
|---|---|
| GitHub org admin | Install the Forge GitHub App and grant repository access. |
| Tenant or account admin | Decide which repos, projects, and apps belong under the customer account. |
| Developer | Configure, onboard, deploy, and troubleshoot the app. |
One person can hold more than one role. The important part is that GitHub App access and repo onboarding are intentional admin decisions, not accidental side effects of a developer command.
Start here¶
- Review Forge architecture for the deploy, request, and access-boundary flows.
- Review the Glossary for Forge, MAP, tenant, account, project, app, deploy, publish, public, and protected terms.
- Review Security and Trust for the deploy, source-access, and credential model.
- Use Connect GitHub to understand the GitHub App installation path and repository access choices.
- Use Account context and app environments to understand the setup context and app environment values used in deploys.
- Use App access and sharing to understand exposure values, platform hostnames, protected access status, and revocation paths.
- Use Versions and publishing to understand how reviewed versions move to the clean public URL and how to move traffic back to a previous reviewed version.
- Use Admin operations runbooks for rollout, onboarding governance, GitHub App grant changes, deploy-failure investigation, publish or restore operations, evidence packets, and app access changes.
- Use Onboard a repo to understand what changes are written into each app repo.
- Use Troubleshooting when setup, source access, route, auth, or runtime readiness fails.
Before developers onboard repos¶
Make these decisions first:
- Which GitHub account or organization owns Forge-deployed repos.
- Whether the Forge GitHub App is granted all repositories or selected repositories.
- The GitHub App installation ref developers pass to
map onboard. - The tenant ref, account ref, and project/app ref for each repo. If
--app-ref/--project-refis omitted,map onboardusesapp:<repo-name>. In the self-service path, this should be the served app ref. - Which apps are intended to be public and which require signed-in access.
- Which domains, email addresses, or
account:principals should reach each protected app. - Who reviews
mithran.yamlchanges before they merge. - Whether the repo needs a custom-CI deploy workflow in addition to webhook deploys.
- Who receives deploy failure reports and investigation evidence.
- Who signs off on the Production checklist before the first customer-visible deploy.
Built-in webhook deploys use the GitHub App path and do not require
deploy keys or long-lived deploy secrets in customer repositories.
Custom-CI deploys use the optional map-deploy.yml workflow when the repo opts
into it during onboarding.
App team onboarding packet¶
Before a developer runs map onboard, give the app team one packet with the
values they should use. Keep this packet free of bearer tokens, GitHub OIDC
tokens, private keys, and raw customer credentials.
| Value | Why the app team needs it |
|---|---|
| GitHub repo | The owner/repo passed to map onboard, map deploy, and repo-scoped grant checks. |
| GitHub App installation ref | The --installation-ref value that authorizes Forge source fetch for that repo. |
| Tenant ref and account ref | The customer boundary recorded by onboarding and app access policy when the account uses these refs. |
| Served app ref | The --app-ref value for the self-service path, usually app:<repo-name>. This is the app identity used by route, version, publish, and optional custom-CI deploy requests. |
| Intended hostname label | The label users expect in https://<label>.apps.mithran.cloud/; keep it aligned with the served app ref and metadata.app_id for self-service apps. |
| Access model | Whether the app should deploy as protected, none, public-redirect, or public, and which domains or principals should be allowed when protected sharing is used. |
| Deploy path | Built-in GitHub App webhooks by default, direct map deploy for explicit requests, or optional custom CI only when customer automation must request deploys. |
| Custom-CI setup values | Only when custom CI is approved: MAP_CONTROL_ENDPOINT and MAP_AUTH_ENDPOINT from account setup, plus any tenant/account/audience values the account requires. |
Ask the developer to return the map onboard output, committed
mithran.yaml diff, map doctor --app <owner/repo> output, and the first
deploy status. Those artifacts prove repo registration, manifest review input,
and the first deploy state without exposing credentials.
Admin decision map¶
Use this table before the first repo is onboarded and again before each customer-visible release.
| Decision | Where it is set | Evidence to keep |
|---|---|---|
| Which repos Forge may read | GitHub App grant: all repositories or selected repositories. | GitHub App installation owner, grant mode, and selected repo list when using selected repos. |
| Which customer boundary owns the app | --tenant-ref, --account-ref, and --app-ref or --project-ref passed to map onboard. |
Onboarding command, map doctor --app <owner/repo>, and the tenant/account/project/app refs used. |
| Which hostname label the app uses | The served app ref used for onboarding, route status, versions, and publish. For self-service apps, keep it aligned with metadata.app_id. |
Onboarding command, reviewed manifest diff, map versions <app>, and the hostname opened during verification. |
| Which refs can deploy | Built-in webhook refs, direct deploy requests, or the optional custom-CI workflow triggers. Built-in defaults are refs/heads/main to preview and refs/heads/release/* or refs/tags/release/* to production. |
Reviewed deploy path decision or reviewed .github/workflows/map-deploy.yml diff. |
| Which app-route exposure value is reviewed | public_edge.exposure in mithran.yaml. |
Reviewed manifest diff, map versions <app>, and allowed/denied HTTP results when relevant. |
| Who can reach a protected app | access.yaml applied with map access plan and map access apply. |
Plan output, apply output, route update or reconcile that carries the policy, and allowed/denied verification. |
| Which version the clean public URL serves | map publish <app> --version <version> or --deployment-ref. |
map versions <app> before and after publish, publish command output, and reviewed source SHA. |
Keep these controls separate. Removing a repo from the GitHub App grant stops new source fetches for that repo, but it is not the same as changing app access or moving the published clean URL.
Review gates¶
Require review for changes that alter deploy authority, source access, route behavior, or customer-visible traffic:
| Change | Review focus |
|---|---|
| GitHub App grant change | Confirm the repo list and whether the change is meant to add source access, remove source access, or both. |
mithran.yaml change |
Check metadata.app_id, identity.project_ref, HTTP capability route, startup command, non-secret environment values, public_edge.exposure, and app-environment metadata. |
| Optional custom-CI workflow | Confirm the repo actually needs custom CI, the workflow is generated with --with-ci-workflow, and it uses GitHub OIDC instead of a stored deploy secret. |
access.yaml change |
Run map access plan, review resolved exposure, allowed_domains, and share, then keep the plan output. |
| Publish or restore | Use the reviewed Git commit SHA as --expected-sha when a human reviewed a specific commit. |
| Route retirement | Confirm the source-access and app-access revocation decisions. Route retirement itself is support-owned. |
GitHub App access choices¶
When installing the Forge GitHub App, GitHub asks whether to grant all repositories or selected repositories.
| Choice | Use when | Tradeoff |
|---|---|---|
| All repositories | The org wants all repos in the GitHub account or organization to be eligible for Forge onboarding. | Less per-repo admin work, broader source access. |
| Selected repositories | The org wants explicit approval for each Forge-deployed repo. | More admin work, narrower source access. |
Developers cannot deploy an arbitrary repo by copying workflow files. The repo must be granted to the GitHub App and onboarded in Forge.
Rollout checklist¶
Use this checklist before asking teams to deploy:
- Confirm the GitHub org owner for Forge-deployed repos.
- Install the Forge GitHub App through the customer setup link when the CLI provides one, and use Connect GitHub for grant scope and evidence.
- Decide all-repos or selected-repos access.
- Identify the first app repo and the admin who approves its GitHub App grant.
- Give developers the GitHub App installation ref, tenant ref, account ref, and
project/app ref to use with
map onboard; for self-service apps, pass it with--app-ref. - Confirm the app has a
Dockerfile, listens on$PORT, and returns HTTP 200 on its local readiness paths. - Review the
mithran.yamlexposure choice and deploy-trigger policy before the first matching webhook ref is pushed. - For protected apps, review the intended access policy and verify the expected allowed and denied results before launch.
- Agree where developers send the Forge deploy status, and the GitHub Actions log when the repo uses custom CI, when deploys fail.
- Require the Production checklist for pilot apps and first customer-visible releases.
Onboarding control points¶
When map onboard runs with --installation-ref <installation-ref>,
<owner/repo>, and --repo-dir <checkout>, it does two admin-relevant things:
- Registers the repo with Forge.
- Writes a starter
mithran.yamlwhen the repo does not already have one.
The starter manifest is a repo-derived HTTP app skeleton, not an approval to deploy unchanged. The app team still owns the reviewed app ID, project/app ref, runtime, startup command, exposure, and app-environment policy.
Use --with-ci-workflow only when a team needs the optional custom-CI workflow.
Without that flag, onboarding does not write .github/workflows/map-deploy.yml
and does not change GitHub Actions configuration.
Review the deployable mithran.yaml like any other deploy-control change. If a
repo was copied from another repo and deploy auth fails, run map onboard again
so the registration matches the new repo.
After onboarding, ask the developer to run:
Treat warnings as signals to inspect the repo grant, onboarding command, and recent deploy status. The public diagnostics can confirm recorded deployments or route aliases, but they do not expose the full repo registration list.
Removing access¶
To stop a repo from deploying:
- Remove the repo from the Forge GitHub App grant in GitHub settings, or remove the app installation from the org.
- Remove or disable the repo's
map-deployworkflow if it uses custom CI and you do not want CI to request deploys. - Follow the route retirement path in App access and sharing if the app route itself must stop serving users.
For app-route exposure and protected-access changes, use App access and sharing.
If source fetch or deploy auth continues to fail after a grant change, use Troubleshooting and include the Forge deploy status plus the GitHub Actions log when custom CI is involved.
For repeatable admin procedures, use Admin operations runbooks.