nomadic project:deploy:quick | report

[mshanemc]

project deploy quick is meant to follow project deploy validate.
validate stores information about the deployment (deployId, orgId) in sf's DeployCache ~/.sf/deployCache.json so that quick can be run using --use-most-recent and not require an ID.

We've seen some open issues around this change, where people want to run these at different times from different machines that don't share a filesystem but somehow passing the job-id around.

One proposed design would be for quick to have a new 3rd option where we'd add a --target-org flag

1. --use-most-recent will read from the deployCache (current behavior)
2. --job-id will read from the deployCache (current behavior)
3. if you supply --job-id and it's not in the cache, BUT you also supplied the target org flag, attempt to run the quick deployment against the specified org. Throw if the target-org is undefined.

copy the same logic for project:deploy:report. This would work with any deployId, not just ones produced by deploy validate

caveat
We would not extend this behavior to the deploy:resume command. That's meant to deal with other scenarios like keeping source tracking files correct after a deployment timeout/interruption that wouldn't be valid on the "do it from different machines" use case.

---

alternatives:

since you're having to share the jobId (deploy id) anyway, why not share the rest of the information with it?

a way to make the deployCache more portable (ex project deploy get to read the cache file, and project deploy set to set the cache file in the new place. Then you'd be passing the full json between systems.

Or we add the deployCache information to the validate/deploy output so that you can send it to the new place using the scripting tools of your choice.

---

reference issues:
#2293 (this one takes a bit to get to the root issue)
#2297
#2078

[scottlee-symmetry]

Hey @mshanemc - this sounds like a reasonable solution. I would add that we'd also want to be able to do this with deploys and not just validations - I'm not sure if that works exactly the same way under the hood minus a flag here or there, or something similar.

[mshanemc]

you'd be able to project deploy report on any deployment. I'll make that clearer

[YodaDaCoda]

One proposed design would be for quick to have a new 3rd option where we'd add a --target-org flag

project deploy quick --deploy-id works fine - it's the deploy resume / deploy report commands that have issues. Seemingly because quick doesn't update the cache file.

I think project deploy quick just needs to add its deployment info to the cache. And it should be the actual quick-deployment job id, not the pre-validated deployment id that it's given that is added to the cache (or both if you like, but most importantly the quick-deploy job).

We would not extend this behavior to the deploy:resume command. That's meant to deal with other scenarios like keeping source tracking files correct after a deployment timeout/interruption that wouldn't be valid on the "do it from different machines" use case.

I'd like to understand this a bit better. The alternative to deploy resume would be deploy report, but it doesn't look like deploy report will work for my use-case, which is to show the deployment progress in the CI log (for review after-the-fact as required), and have the CI wait for the deploy job to complete so it can report completion status & perform post-processing. deploy report instantly returns the current status of the job, and doesn't seem to support waiting for the job to complete. True that keeping source tracking files correct wouldn't be valid, but the purpose of the command (from the user's perspective - synchronously waiting for the deploy job to complete and outputting status every few seconds) is valid. Also, if the deploy job is already complete when you run deploy resume then the command throws an error (which I also don't like btw) - surely the source-tracking doesn't get updated in this case?

3. if you supply --job-id and it's not in the cache, BUT you also supplied the target org flag, attempt to run the quick deployment against the specified org. Throw if the target-org is undefined.

I'm authorising with sf org login sfdx-url --set-default. Part of the beauty of this is that I don't need to worry about usernames, aliases, or setting --target-org anywhere. I'd strongly prefer sf to simply accept the job-id provided, request information from the org, and throw an error if the org says it can't find a deployment with that id. I find the current behaviour, where the cache is a source-of-truth, to be very counter-intuitive.

since you're having to share the jobId (deploy id) anyway, why not share the rest of the information with it?

I'm getting the jobId from the project deploy start --json command and saving it in an artifact that I have control over and which is accessible between different pipelines. Saving/restoring sf internal cache files seems fragile & would come with other penalties (such as increased storage consumption on a limited resource) - can we please avoid this?

tl;dr

The cache is nice, but shouldn't be a source of truth. The org is the source of truth. If a deploy id isn't in the cache, just query the org. And return the new job id when doing project deploy quick.

Sidenote:

I find it really weird that sf project deploy quick doesn't output the newly-created quick-deployment job id, instead showing the original pre-validated job id. sfdx force:source:deploy --validateddeployrequestid does output the newly-created deploy id, which makes reporting easy. sf project deploy quick also doesn't seem to update the cache file, either to amend the original deployment and link it to the quick-deploy job, or to add the quick-deploy job and link it to the original deployment (either would make sense, but the latter probably moreso). This would seem to indicate that sf would have to search for the quick-deploy, rather than simply querying for it by the new id. In fact, attempting to report on a quick-deployment just gives the status of the original deploy job.

[mshanemc]

If a deploy id isn't in the cache, just query the org

yeah, that's what target-org would enable. One of the requests that lead to "nomadic" is this:

• one ephemeral CI job runs and does a validate
• some other CI job or human wants to quick or report on that one, but can't because they're missing the cache because different machine, so they need to specify an org.

target-org flag uses the default org (by default) so this wouldn't add a requirement to specify it unless you supply a job ID and don't have it in the cache--then we could go target the org.

[mshanemc]

Saving/restoring sf internal cache files seems fragile & would come with other penalties (such as increased storage consumption on a limited resource) - can we please avoid this?

they're time-limited (7 days). Theuse case for the cache was making it possible to retry/continue stuff without having to do the --json > and then read that, etc. to get at the deployIds. It's also consistent with how scratch/sandbox and some other "resumable" commands work.

[mshanemc]

am with you on quick outputting the IDs in a better way and straightening out how those queries work.

[YodaDaCoda]

I have got part way towards achieving my expected behaviour with the following patch. Unfortunately I still get undefinedComponentSet during the deploy report phase.

fix-quick-deploy.patch

[nwcm]

I want to add my two cents here because the path from sfdx -> sf and these new changes has me frustrated at the CLI consistency. We almost exclusively use SF CLI commands in CI/CD and not locally. The latest changes seem to be geared heavily to local development for small teams and not enterprise workflows.

CLI commands should not be dependent on filesystem information. I believe all commands should accept parameter's for the org for extensibility within complex CI/CD pipelines.

It seems common in the CLI space to align closely to the REST service, but I've found this sf change seems further from the Salesforce REST service.

[AllanOricil]

@mshanemc you could add a new env variable which let us control where the global cache is stored SF_GLOBAL_CACHE_PATH. this way we configure our cicd pipelines to cache and restore this path when running workflows on different machine.

[mshanemc]

these always go to ~/.sf/deploy-cache.json and ~/.sf/manifestCache/*.

We have a separate request for letting people choose a different place for all of ~/.sf

the biggest concern with that technique would be the possibility of 0Af keys colliding across different orgs.

[mnunezdm]

Caching and restoring ~/.sf folder does the trick

[mnunezdm]

Why the --target-org is not going to be available in sf project deploy? That script is great for keeping track of the status of a deployment, and also for polling until the deployment is finished

The sf project deploy report without a --wait makes no sense for me, It is necessary to manually poll a deployment

❯ sf project deploy report --job-id 0Af1q00001fUUDcCAO           
0Af1q00001fUUDcCAO... InProgress

Deploy Info
===================================================
| Key                      Value                    
| ──────────────────────── ──────────────────────── 
| checkOnly                true                     
| createdBy                0053W000000SkTN          
| createdByName            MIGUEL NUÑEZ DIAZ-MONTES 
| createdDate              2023-09-05T11:59:53.000Z 
| done                     false                    
| id                       0Af1q00001fUUDcCAO       
| ignoreWarnings           true                     
| lastModifiedDate         2023-09-05T11:59:58.000Z 
| numberComponentErrors    0                        
| numberComponentsDeployed 1                        
| numberComponentsTotal    1                        
| numberTestErrors         0                        
| numberTestsCompleted     0                        
| numberTestsTotal         0                        
| rollbackOnError          true                     
| runTestsEnabled          true                     
| startDate                2023-09-05T11:59:53.000Z 
| status                   InProgress               # 😵‍💫
| success                  false

Also sf project deploy resume fails if the deployment is already finished and has succeded, this implies adding additional validations to build pipelines

❯ sf project deploy resume --job-id 0Af1q00001fUUJUCA4
Error (1): Job ID 0Af1q00001fUUJUCA4 is not resumable with status Succeeded. # error and succeded in the same line 😵‍💫

[shetzel]

Good news! - I believe everything discussed in this thread has been addressed and is in the CLI release candidate published about an hour ago. sf v2.11.7. See the release notes here or run sf whatsnew -v latest-rc.

[AllanOricil]

maybe if it was 42 it would have worked 🤭

[mnunezdm]

Its present in the description but not in the flags section

[AllanOricil]

I believe job Id is enough to identify the org. Isn't it?

[shetzel]

Looks like I missed the nightly release by an hour on Wednesday so the promotion that happened Thursday didn't include v1.18.2 of the deploy-retrieve plugin which has the updated command. You can manually update that plugin to get v1.18.2 for the time being. I will patch the CLI release candidate to have v1.18.2 asap and notify you when it's complete. Sorry about that!

[AllanOricil]

[shetzel]

@mnunezdm - sf v2.11.8 is now available as the CLI release candidate and I verified it has the updated deploy-retrieve plugin and updated command. Thanks for pointing that out!

[shetzel]

sf v2.11.8 is now the production version. Everything in this thread should be addressed in that version, but as always let us know if it isn't. Big thanks to everyone involved in getting this implemented!

[georgekaz]

sf project deploy cancel doesn't support --target-org and ticket #2421 which discusses this has been closed because it's supposed to have been implemented via this discussion. Is there any way this can be implemented? The cache folder option is not possible in our scenario. Thanks

[cristiand391]

Are your team planning to add target org support to project deploy resume?

no, that command also updates source tracking and is expected to be used after a local deploy.

[georgekaz]

Because sf project deploy report stops with a successful return code after the wait period even if the deployment hasn't finished, I have to use sf project deploy resume to monitor the deployment (as far as I am aware).

In case anyone else is interested, here is my workaround for starting, passing the cache folder between jobs and resuming in a simplified github actions pipeline:

jobs:
  start_deploy:
    outputs:
      deployment_id: ${{ steps.deploy.outputs.deployment_id }}
      sf_cache: ${{ steps.cache.outputs.sf }}

    steps
    - name: Start deployment
      id: deploy
      run: |
         [prep, auth etc]
         DEPLOY_OUTPUT=$(sf project deploy start --async [options])
         DEPLOYMENT_ID=`echo ${DEPLOY_OUTPUT} | jq -r '.result.id'`
         echo "deployment_id=$DEPLOYMENT_ID" >> $GITHUB_OUTPUT
      
    - name: Output cache
      id: cache
      run: |
        tar -zcvf /tmp/sf.tgz -C ~ .sf
        echo "sf=$(cat /tmp/sf.tgz | base64 -w 0)" >> $GITHUB_OUTPUT

  monitor_deploy:
    needs: start_deploy

    steps:
    - name: Restore cache
      run: |
        echo ${{ needs.start_deploy.outputs.sf_cache }} | base64 -d > sf.tgz
        tar -zxvf sf.tgz -C ~
        
    - name: Watch deployment
      run: |
         [prep, auth etc]
         sf project deploy resume \
              --job-id $DEPLOYMENT_ID \
              --wait 180

[georgekaz]

@cristiand391 I have a workaround I'm happy with but I thought I might explain the requirement. If you start a deployment that takes a long time, there's the chance that the wait will timeout. If that happens, you want to be able to resume watching the existing deployment without starting a new one. For this to be possible the CI needs to be in 2 different jobs (start & monitor) so you can restart one without the other. If they are in different jobs, they are nomadic and the .sf folder is not shared. As mentioned before, sf project deploy report does not accurately monitor when a deployment has finished so cannot be used as an alternative.

[cristiand391]

gotcha, yeah that's a perfectly valid use-case.

About making the command return exit code > 0 if the deploy didn't finish:
there are actually a few reasons the deploy might fail, maybe code 0 for a successful deploy is fine but we would have to define other codes for the rest of options. If you have any suggestions/ideas for improvement maybe can open a new post here:
https://github.com/forcedotcom/cli/discussions/categories/ideas

maybe a --fail-fast flag to make the command fail on first failure? (like GitHub CLI's gh pr checks).

Aside from exit codes, sf project deploy resume --json includes the deploy status in the output so you could use jq to check that and make the CI job fail on failure or even re-run the command again if the deploy is stil in-progress.

possible states:

["Pending", "InProgress", "Succeeded", "SucceededPartial", "Failed", "Canceling", "Canceled"]

[georgekaz]

Aside from exit codes, sf project deploy resume --json includes the deploy status

I assume you mean sf project deploy report --json. I suppose combined with the new --wait that was added in October '23 this could be used instead of resume and then as you say, the json can be used to check the status. I actually already use that before resuming anyway. Because there was previously no wait on report, it was not possible.

My existing pipeline includes

    - name: Watch deployment
      run: |
        DEPLOYMENT_ID=${{ needs.start_deploy.outputs.deployment_id }}
        if [ "$DEPLOYMENT_ID" != "" ]; then

          # Get a report to check that the deployment is still running
          echo "Getting report for Job: $DEPLOYMENT_ID"
          REPORT_OUTPUT=$(sf project deploy report \
                          --job-id $DEPLOYMENT_ID \
                          --json)
          DEPLOYMENT_STATUS=`echo ${REPORT_OUTPUT} | jq -r '.result.status'`
          
          if [ "InProgress" = "$DEPLOYMENT_STATUS" ] || [ "Pending" = "$DEPLOYMENT_STATUS" ]; then
            # Resume watching the deployment
            echo "Resuming deployment: $DEPLOYMENT_ID"
            sf project deploy resume \
              --job-id $DEPLOYMENT_ID \
              --wait ${{ inputs.report_wait_timeout }}
          fi
        else
          echo "Deployment Id is missing"
          exit 1
        fi