Connect a Repository | ArchPilot Docs

Search docs

Docs search

Connect a Repository

Connect one repository to ArchPilot Cloud with an organization API token so local validation results can become shared governance snapshots intentionally.

Why it matters

Use this page when you want exact product steps for taking a repository from local-only validation to Cloud-backed repository history, findings, and governance visibility.

Plan availability

ALL PLANS

Manual governance upload

Upload a validated snapshot from the CLI, extension, or Inspector when you want to publish a Cloud checkpoint.

PAID PLANS

Automatic CI-to-Cloud upload on main

Upload automatically from GitHub Actions after main-branch validation succeeds.

Start with the correct authentication model

People sign in to ArchPilot Cloud with their user account. Automation uploads governance data with an organization API token.

Those two flows are intentionally separate so a developer login never becomes the upload credential for CI or automated upload.

Create the upload token in ArchPilot Cloud at Settings, Tokens.
The full token value is shown once, then only a hash and safe prefix remain in Cloud.
Use this URL in the CLI and in GitHub Actions configuration.

Use the ArchPilot Cloud URL:

https://api.archpilot.org

Connect a repository step by step

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.

Sign in to ArchPilot Cloud.
Create or select the organization that should own the repository's governance history.
Open Settings, then Tokens.
Create a new organization API token.
Copy the token immediately while it is shown.
(Optional) Configure the repository's local Cloud connection using .archpilot/config.json.
Run archpilot validate to generate the current local artifacts.
Run archpilot governance upload with https://api.archpilot.org and your organization API token.
Open Repositories in Cloud and confirm the repository and latest snapshot appear.

Validate locally:

archpilot validate

Upload explicitly:

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

What gets uploaded

Cloud stores the validated result produced locally or in CI.

Repository matching is organization-scoped and is based on stable external repository identity such as github.com/<owner>/<repo>.

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

Persist the Cloud connection locally when it helps

A repository can keep a saved Cloud connection for repeated local uploads.

This optional saved connection works well for local workflows when the same repository uploads to the same organization repeatedly.

API tokens support manual uploads on all plans. Automated CI uploads require a paid plan.

cloud.server: https://api.archpilot.org
cloud.token: the organization API token used for governance upload
cloud.uploadOnValidate: an opt-in convenience flag for local workflows when the team intentionally wants validation to trigger upload through the saved connection

Example .archpilot/config.json cloud block

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

Common mistakes

Using the wrong token. Use your organization API token from ArchPilot Cloud.
Expecting archpilot validate to upload by itself.
Trying to upload before validation artifacts exist.
Using an expired or revoked token.
Using the wrong ArchPilot Cloud URL.

API Tokens & Upload Connection Governance Upload Upload Troubleshooting

Next steps

Repositories & Snapshots Findings & Exceptions