Upload Troubleshooting

Start with the simple checks

1. Confirm that archpilot validate completed successfully and current artifacts exist in .archpilot/reports or related local ArchPilot output files.
2. Confirm that the upload command uses an organization API token from Cloud Settings, Tokens.
3. If you are uploading from GitHub Actions, confirm that the workflow has the ARCHPILOT_API_TOKEN repository secret configured.

Workflow generated or configured, but upload is skipped

The standard GitHub Actions workflow uploads only on pushes to main, and only when ARCHPILOT_API_TOKEN is configured.

If the token secret is missing, the workflow should print the explicit skip message instead of failing validation because Cloud upload is an optional follow-up step.

If the workflow reaches the upload step but the API rejects the request, check the organization plan. Manual governance upload is available on all plans, and automatic CI upload on main is available on paid plans.

• Check that the run was triggered by a push to main, not a pull_request run.
• Check that ARCHPILOT_API_TOKEN is present in GitHub Actions repository secrets.
• Check the workflow log for the explicit skip message before assuming upload is broken.
• If the error says automatic CI governance upload is not available on the Free plan, run manual upload or use a paid plan for automatic CI upload.

Token is wrong or no repository appears in Cloud

The most common cause is using the wrong token. Governance upload needs an organization API token created in ArchPilot Cloud.

If the token was copied incorrectly, revoked, or expired, the upload request will not be accepted even though validation succeeded locally.

• Recreate the token in Cloud Settings, Tokens and copy it immediately while the full value is shown.
• Replace the stored token value in your saved connection or CI configuration.
• Use your organization API token from ArchPilot Cloud for governance upload.

Upload command or token is wrong

Production uploads use the official ArchPilot Cloud/API service. Users normally provide only the organization API token.

If local uploads keep failing, validate first, then retry the explicit upload command with a current organization API token.

• Use an organization API token from Cloud Settings, Tokens.
• For automatic GitHub Actions upload, store the same token as ARCHPILOT_API_TOKEN.

archpilot validate

archpilot governance upload --token <organization-api-token>

Validate failed, so upload never ran

Validation is the blocking step in the documented workflow. Governance upload is intentionally downstream from validation so Cloud receives a validated snapshot instead of a partial or failed run.

If validate fails in CI, fix the architecture or setup issue first. Upload will not run until validation succeeds.

Baseline is missing or invalid

A missing or invalid baseline can affect review expectations or drift comparisons, but it is not the same thing as Cloud upload configuration.

If your team expects baseline-based drift output, refresh the local baseline workflow separately with the baseline commands described in the CLI reference.

• Use archpilot baseline create for the first accepted baseline.
• Use archpilot baseline check for structural drift comparison.
• Use archpilot baseline refresh when later runs need a refreshed governance/history reference.

PR comments or review output are missing

The generated workflow publishes PR review context on pull_request runs after validation succeeds.

`archpilot ci github` publishes or updates the ArchPilot PR comment. If the comment is missing, confirm the run was a pull_request event and that the workflow has pull-requests: write permission.