Context

Used as a part of the endorctl scan command.

https://docs.endorlabs.com/developers-api/cli/commands/scan/

Implications:

• Using this flag causes the scan to create a new RepositoryVersion resource under the existing Project context with the provided name (regardless of this ref actually existing or not)

• Any SAST / Secrets finding with a Location URL attribute will be generated with the string established as the name of the RepositoryVersion in the URL.

Answer

Usage Guide:

• This flag is not necessary for GitHub Actions (due to CI not using shallow cloning)

• Use the envars specific to each CI for their branch names:

  • Gitlab: CI_COMMIT_REF_NAME 

  • Jenkins: BRANCH_NAME / GIT_BRANCH

  • ADO:

    • NOTE: Must strip refs/heads/ from the values returned by

      Build.SourceBranchName environment variable prior to use.

  • CircleCI: CIRCLE_BRANCH / CIRCLE_TAG

  • BitBucket: BITBUCKET_BRANCH /BITBUCKET_TAG

Key Takeaway

The central point is to avoid using --detached-ref-name in standard CI/CD environments where the correct branch/ref information is already available via environment variables.

• Risk: Using this flag with a non-existent name (like 'THIS-BRANCH-DOESNT-EXIST') forces endorctl to create a fictional RepositoryVersion. As your example shows, this generates broken location_urls for findings, making them difficult to trace back to the source code.

• Correct Method: In a CI pipeline, you should always use the platform-specific environment variables to ensure scans are associated with the correct, existing code reference.

Evidence:

1. endorctl scan --languages=python --secrets --detached-ref-name 'THIS-BRANCH-DOESNT-EXIST'

2. endorctl api get --resource Finding --uuid 690a77a1c9b2ec0ed54d8a51 -n endorlabs.endor-mock.devopstest-repos --field-mask spec.location_urls
   

   Example Output - This location field doesn't route to anything and is an invented consequence of using --detached-ref-name incorrectly.

   {
     "spec": {
       "location_urls": {
         "passwordApiSpec.js": "https://dev.azure.com/endor-mock/devops.test-repos/_git/devops.vuln-sandbox?path=/passwordApiSpec.js&version=GBTHIS-BRANCH-DOESNT-EXIST"
       }
     },
     "uuid": "690a77a1c9b2ec0ed54d8a51"
   }