HubSpot CLI, Node, and CI Preflight Checklist

Record local and runner Node versions, the locally tested HubSpot CLI version, repository working directory, project path, `platformVersion`, target account, and config profile when used. At the 2026-08-29 live check, HubSpot's installation guide supports Node.js 20 or higher, and the official GitHub Actions guide requires an existing HubSpot project on platform version 2025.2 or higher.

Choose one of two official credential paths; do not mix them. The basic, single-account workflow creates repository secrets named exactly `HUBSPOT_ACCOUNT_ID` and `HUBSPOT_PERSONAL_ACCESS_KEY`, maps them to `DEFAULT_ACCOUNT_ID` and `DEFAULT_PERSONAL_ACCESS_KEY`, and runs `HubSpot/hubspot-project-actions@v1.1.0`. Never put either secret value directly in YAML, source, logs, tickets, or agent prompts.

A config-profile or multi-environment workflow is different. Commit the non-secret `hsprofile.*.json` files, create an account-ID and personal-access-key secret pair for each environment, and use `HubSpot/hubspot-project-actions/project-upload@v1.1.0` with explicit `with` inputs for `profile`, `account_id`, and `personal_access_key`. HubSpot warns that the basic workflow's `env` approach does not propagate correctly when profiles are used.

Place each workflow under `.github/workflows/`, quote branch values such as `"main"`, and match each profile, account ID, secret pair, branch, and workflow file deliberately. For the basic action only, optional `DEFAULT_CLI_VERSION` should be a fixed, tested release instead of `latest` or `next` when overriding the predetermined stable default.

Inventory the values CI needs, but do not paste tokens, client secrets, private keys, or account credentials into docs, tickets, or agent prompts. The handoff should say where secrets live, who owns them, and which environment uses them.

Review logs for accidental disclosure. A migration or upload workflow is not ready for client handoff if command output could expose OAuth secrets, tokens, or internal account IDs unnecessarily.

For agencies, separate client-facing evidence from internal build details. The client may need proof of version checks and source verification, not raw secret names or CI internals.

The documented success path is: a push to the configured branch starts the workflow, the HubSpot action validates and uploads the project, the GitHub run completes, and HubSpot Builds & Deploys shows the resulting build. HubSpot attributes action-triggered builds with the commit message and SHA, so record that SHA, build result, deployment result, and the account/environment that received it.

If the workflow does not parse, quote branch values such as `"main"`. If profile support is missing, confirm the sub-action is at least `project-upload@v1.1.0`. If a profile targets the wrong account or authentication fails, verify the committed profile's `accountId`, its environment-specific secret pair, the explicit `with` inputs, and `${{ secrets.SECRET_NAME }}` references; do not switch back to the basic `env` pattern. If no run starts, check the branch, `.github/workflows/` path, extension, and whether Actions is disabled.

Triage before retrying: a Node or dependency-install error belongs to runner/toolchain setup; a lint or validation error belongs to project/configuration readiness; a wrong account/profile or project-directory result belongs to targeting; and missing or ambiguous command JSON belongs to observability. In the last case, inspect HubSpot Builds & Deploys and `hs project list-builds` instead of inferring that no build was created from one missing field.

A green GitHub job without a matching HubSpot build is not accepted, and a successful build is not automatically a successful deployment or install. Open `hs project open` or the Projects dashboard, review Builds & Deploys, and run the written install/feature smoke tests before promotion. Keep QA and production accounts on separate branch/profile/secret paths when you adopt HubSpot's multi-environment pattern.