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 https://api.archpilot.org and an organization API token from Cloud Settings, Tokens.
3. If you are uploading from GitHub Actions, confirm that the workflow has both the ArchPilot Cloud URL and organization API token configured.

Workflow generated or configured, but upload is skipped

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

If the Cloud connection is missing, the workflow should skip upload 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 both the ArchPilot Cloud URL and organization API token are present in GitHub Actions configuration.
• 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.

Cloud URL is wrong

Use the same ArchPilot Cloud URL in local setup and in GitHub Actions.

A wrong Cloud URL often looks like a valid command that never lands in the expected Cloud workspace.

• Use https://api.archpilot.org.
• Check the saved Cloud connection value if local uploads keep failing in the same way.

https://api.archpilot.org

archpilot validate

archpilot governance upload --server https://api.archpilot.org --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 or refresh when later runs need drift comparison or a refreshed accepted reference.

PR comments or review output are missing

The standard workflow is validation-first and Cloud-upload-on-main. PR review comments are optional and depend on how your team configures the workflow.

If you add comment or review publishing, treat it as an add-on to the validation workflow rather than the source of truth for pass or fail.