hardis:project:deploy:cancel
Description
Command Behavior
Cancels in the Salesforce org the deployment simulation started by the current CI job, when this CI job is cancelled.
When a CI job running hardis:project:deploy:smart with --check is cancelled (for example when a new commit is pushed on the Merge Request), killing the job does not stop the deployment simulation in the org. Salesforce keeps it running, and the next simulations on the same org wait for it.
Call this command from the cancellation hook of your CI job, after the job has been cancelled:
- GitLab:
after_script, when the job did not succeed and its job id file exists - GitHub Actions: a step with
if: cancelled() - Azure Pipelines: a step with
condition: canceled() - Jenkins:
post { unsuccessful }of the stage that runs the simulation
Bitbucket Pipelines runs no script when a step is stopped or times out, so a stopped simulation cannot be cancelled there.
The default sfdx-hardis CI/CD templates already do it.
Key behaviors:
- Only the simulation of this CI job: it never cancels the deployment of another Merge Request, even if both target the same org with the same user, as long as each CI job runs in its own container, as in the default templates. When several jobs run at the same time on the same host without a container (GitLab shell executor, self-hosted GitHub or Azure runners) and share the same home folder, a job can record and cancel the simulation of another one.
- Simulations only: a real deployment is never cancelled.
- Never fails: if there is nothing to cancel, or if the deployment is already completed, it logs the reason and exits with code 0, so it cannot make a CI job fail.
Agent Mode
Supports non-interactive execution with --agent:
sf hardis:project:deploy:cancel --agent
This command has no interactive prompt: --agent changes nothing, it is accepted for consistency with other commands.
Technical explanations
- Job id recording: in CI, while
sf hardis:project:deploy:smart --checkrunssf project deploy start --dry-run, it watches the Salesforce CLI deploy cache (~/.sf/deploy-cache.json) and writes the job id of the new simulation in.cache/sfdx-hardis/running-deployment-simulation.json, in the working tree. The file is deleted when the deploy command succeeds, and by this command once it has used it. It is kept after a failed deploy command: when a CI job is cancelled, some runners (GitLab) kill the deploy command first, so the failure can be the cancellation itself. If the simulation is already completed, this command logs it and does nothing. - Why the working tree: with some CI executors (GitLab Docker executor), the cancellation hook runs in a new container where the home folder of the job, and its Salesforce CLI cache, are lost. The working tree is kept.
- Cancellation: runs
sf project deploy cancel --job-id <id> --target-org <username> --async. On GitLab Docker executor, runsf hardis:auth:loginbefore, as the authentication of the job is lost too. - GitLab timeout: GitLab runs no
after_scriptonce a job reaches its timeout. The default template setsRUNNER_SCRIPT_TIMEOUT5 minutes below the job timeout, so the hook still runs. Raise both together. - Result: returns
status(canceled,nothing-to-cancel,already-completed,skipped-not-simulationorfailed),jobIdandtargetUsername.
Parameters
| Name | Type | Description | Default | Required | Options |
|---|---|---|---|---|---|
| agent | boolean | Run in non-interactive mode for agents and automation | |||
| debug -d |
boolean | Activate debug mode (more logs) | |||
| flags-dir | option | Import flag values from a directory. | |||
| json | boolean | Format output as json. | |||
| websocket | option | Websocket host:port for VsCode SFDX Hardis UI integration |
Examples
$ sf hardis:project:deploy:cancel
$ sf hardis:project:deploy:cancel --agent