Enterprise Setup

A single dev can run appilots sync from a laptop. A team shipping to production wants environments, review gates, and least-privilege access. This is a checklist of recommendations, not a rigid sequence — adapt it to your org.

Environments and keys

• One project per environment (or at least one API key per environment): a Fleet App — Staging project and a Fleet App — Production project, each with its own key. Keys are scoped to a single project, so a leaked staging key never touches production data.
• One key per distribution channel where builds diverge (internal beta vs. store release), so any one key can be revoked without taking every build down. See Projects & API keys.
• Keys live in CI secret stores and .appilotsrc files that are git-ignored — never in committed source. appilots init git-ignores .appilotsrc for you; CI should use the APPILOTS_API_KEY env var and no file at all (CI integration).

CI as the source of truth for MCP documents

Hand-run syncs drift. Make CI own the upload:

- name: Sync Appilots MCP document
  run: npx --yes @appilots/cli sync --json --strict-metadata
  env:
    APPILOTS_API_KEY: ${{ secrets.APPILOTS_API_KEY }}
    APPILOTS_SERVER_URL: https://api.appilots.com

• --strict-metadata fails the build when a mutating action lacks effect/riskLevel (Metadata quality) — this is your merge gate against unlabeled destructive actions reaching users.
• --json gives pipelines a parseable result; the checksum-based skip makes re-runs idempotent and cheap (CI integration).
• Run it after tests, on the same branch protections as your deploy, so the active MCP document always corresponds to a build that actually shipped.

Team roles

Appilots workspaces have four roles — owner > admin > member > viewer (Team management). Least-privilege defaults that work for most teams:

Who	Role
Workspace creator / billing owner	owner
Platform/infra leads who manage keys and webhooks	admin
Engineers and support operators	member
Stakeholders who only read dashboards	viewer

Permissions and budget

• Set project-level permissions in the dashboard as the baseline (Permissions, budget & personalization), and tighten further per build with SDK-side permissions where a given app variant needs less (e.g. a read-only kiosk build with canSubmitForms: false).
• Configure a budget so a runaway usage spike degrades gracefully instead of surprising finance.

Integrations and monitoring

• Webhooks (Dashboard → Webhooks) push project events into your existing tooling. Verify the HMAC signature on every delivery.
• Human escalation needs an owner on the support side: decide who watches the queue and claims handoffs (Human escalation ops) before you ship the feature to users.
• Usage & analytics (dashboard) is your rollout health check — watch failed/abandoned interactions per screen to find where MCP metadata needs investment.

Pre-launch checklist

• Separate keys per environment; production key only in production CI/infra
• .appilotsrc git-ignored everywhere; no keys in app source or repo history
• appilots sync --strict-metadata green and wired into CI
• Destructive actions all carry effect/riskLevel/confirmation metadata
• Project permissions reviewed against Security best practices
• Escalation queue ownership assigned
• Budget configured