HubSpot hs project upload Checklist

Treat `hs project upload` as a change-management moment, not a casual sync command. The official project commands docs describe it as uploading a project to HubSpot and creating a build, with auto-deploy behavior depending on project settings. That means the checklist should start with the target account, the current project state, and whether a successful build can become a deployed change.

Run from the intended project root: record the working directory and confirm its top-level `hsproject.json` names the project you intend to upload. If the command cannot resolve a project, fix the directory or project structure rather than retrying from an arbitrary parent folder.

Confirm which account name in `~/.hscli/config.yml` is intended for the upload. HubSpot documents `--account=accountName` for targeting a specific account, including workflows that move from sandbox to main account. For agency work, make the account name explicit in the handoff so a developer is not relying on whichever account was last authenticated in a terminal.

If the team uses config profiles, record both the requested profile and the account it is expected to select. After upload, verify the actual project/account through build history and `hs project info --json`; do not assume that a syntactically accepted profile or account argument reached the intended environment.

Inspect `hsproject.json`, `app-hsmeta.json`, and feature configuration before upload. If you changed OAuth settings, redirect URLs, scopes, app cards, settings pages, or other JSON configuration, record exactly what changed and why. Keep UID changes especially visible because the create-app docs warn that changed UIDs can make the platform treat a component as different from previous builds.

The most important SEO answer for searchers is simple: upload and deploy are related but not identical. `hs project upload` creates a build. If the project is configured to auto-deploy, that successful build can deploy automatically; if it is not, a manual deploy step may be needed. Always check current project settings and current docs before giving a stakeholder a go-live expectation.

For a sandbox-to-main workflow, use a written release note even if the code change is small. Include the command planned, account target, expected build behavior, rollback owner, and what to test after upload. This is especially useful when an AI agent or junior developer is preparing the command but a senior developer owns the account consequence.

Do not describe this guide as a deployment guarantee. A clean local project and a correct command can still fail because of account permissions, app configuration, platform validation, missing backend OAuth configuration, Marketplace requirements, or changes in HubSpot documentation after this source-check date.

A useful pre-upload packet contains: source-check date, CLI version, target account, project directory, changed files, expected auth mode, redirect URLs, scopes, UID changes, auto-deploy setting, test plan, and owner. That packet is small enough to paste into a pull request, issue, or client delivery note.

For public or Marketplace apps, connect upload readiness to install-flow readiness. HubSpot's create-app docs describe post-upload work around installation and OAuth app credentials. If your backend OAuth server still lacks the correct client ID or client secret, an uploaded project is not the same as a tested app.

After upload, capture build result, deploy result if applicable, app install result, and any manual follow-up. Those notes help the next developer distinguish a command failure from an auth failure, a Marketplace readiness gap, or an unsupported assumption.

Run `hs project validate` before upload and resolve every reported `app-hsmeta.json` readiness problem. After upload, run `hs project list-builds --limit 5` and use `hs project open` to confirm the new build ID, status, auto-deploy outcome, and target account. `hs project info --json` can provide machine-readable project and component metadata when a handoff or CI check needs it.

Split failures by layer. Validation failure means repair configuration and do not upload. Build failure means inspect Builds & Deploys and the reported source error before creating another build. A successful build with a failed install belongs in the OAuth, scope, permission, or static-auth path. For runtime or authorization behavior in an installed app, use the current `hs app logs` filters such as `--errors-only` and `--since 1h`; `hs project logs` is specifically for a project's function logs.

Do not use `--force` as generic recovery; HubSpot documents it as bypassing warnings for destructive actions. If auto-deploy is off, `hs project deploy --build <verified-build-id>` can deploy a specific successful build. If a deployed change regresses, first confirm an earlier known-good build ID and its compatibility in Builds & Deploys, assign the rollback owner, and only then use the documented specific-build deploy path. A previous build is not automatically safe for changed auth, data, or Marketplace state.