Governance Upload

The core model

Validation is local. Governance upload is explicit. ArchPilot Cloud stores the resulting governance snapshot, but it does not become the validator.

That split is intentional: developers and CI produce the validated result locally, and Cloud becomes the shared visibility and history layer.

Validation must run before upload so ArchPilot can generate the required artifacts.

Manual governance upload is available on all plans. Automatic CI upload to Cloud on main is available on paid plans.

• Run archpilot validate first so the repository has fresh local artifacts.
• Run governance upload only when you want the current result stored in Cloud.
• Use an organization API token for upload. Human sign-in to the web app stays separate.

https://api.archpilot.org

archpilot validate

archpilot governance upload --server https://api.archpilot.org --token <organization-api-token>

What must exist before upload

If upload says required artifacts are missing, run archpilot validate first and then retry the upload.

Do not assume validate uploads automatically. Upload is a separate action unless you have explicitly opted into saved upload-on-validate behavior in local config.

• A validated local repository state, including the current findings and summary artifacts.
• ArchPilot Cloud URL set to https://api.archpilot.org.
• An active organization API token created from ArchPilot Cloud.
• A repository identity that can be resolved from the Git remote or the upload payload.

What upload stores in Cloud

Cloud stores the validated result produced locally or in CI.

• Repository identity and context
• Snapshot summary with branch and commit details when present
• Findings and findings summaries
• Architecture score and governance signals
• Snapshot history and posture trend signals

Use saved project config when it helps

Some ArchPilot clients persist the Cloud connection in .archpilot/config.json so you do not need to pass server and token flags every time.

A saved Cloud connection can include the Cloud URL, organization API token, and upload-on-validate preference. Treat the token as sensitive.

• Explicit flags override ambiguity in scripts and CI because the command shows exactly which server and token are being used.
• Saved config is convenient for local developer workflows when the same repository uploads to the same organization repeatedly.
• uploadOnValidate should be treated as an opt-in convenience. Use it only when your team explicitly wants validation to trigger upload from the saved Cloud connection.

{
  "cloud": {
    "server": "https://api.archpilot.org",
    "token": "ap_live_1234567890_example",
    "uploadOnValidate": true
  }
}

When teams use upload

Manual governance upload is available on all plans. Automatic CI upload to Cloud on main is available on paid plans.

• After local validation succeeds and a team wants a shared checkpoint
• In CI on important branches when the organization wants architecture history in Cloud
• When platform or governance teams want organization-wide visibility without moving validation into a hosted scanner

Common mistakes

• Using the wrong token. Use your organization API token from ArchPilot Cloud.
• Expecting archpilot validate to upload automatically.
• Trying to upload before validation artifacts exist.
• Using a revoked or expired token and assuming the upload will still succeed.
• Using the wrong ArchPilot Cloud URL.

What upload does not change

Governance upload does not turn Cloud into the validation engine. Cloud is the visibility and governance layer, not the place where architecture validation is computed.

Most teams start with local validation, then add governance upload when they need shared history, dashboards, ownership, policy workflows, and cross-repository findings visibility.