docs: clarify repo flag requirements and stable ID guidance

cmd/kosli/attestArtifact.go

@@ -48,8 +48,11 @@ const attestArtifactShortDesc = `Attest an artifact creation to a Kosli flow.  `
 
 const attestArtifactLongDesc = attestArtifactShortDesc + `
 ` + fingerprintDesc + kosliIgnoreDesc + `
-This command requires access to a git repo to associate the artifact to the git commit it is originating from. 
-You can optionally redact some of the git commit data sent to Kosli using ^--redact-commit-info^`
+This command requires access to a git repo to associate the artifact to the git commit it is originating from.
+You can optionally redact some of the git commit data sent to Kosli using ^--redact-commit-info^.
+To record repository information, all three of ^--repo-id^, ^--repo-url^, and ^--repository^ must be set together.
+These are automatically set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps.
+In other CI systems, set them explicitly to capture repository metadata.`
 
 const attestArtifactExample = `
 # Attest that a file type artifact has been created, and let Kosli calculate its fingerprint
@@ -149,7 +152,7 @@ func newAttestArtifactCmd(out io.Writer) *cobra.Command {
 	cmd.Flags().StringToStringVar(&o.externalURLs, "external-url", map[string]string{}, externalURLFlag)
 	cmd.Flags().StringToStringVar(&o.annotations, "annotate", map[string]string{}, annotationFlag)
 	cmd.Flags().StringVar(&o.repoID, "repo-id", DefaultValue(ci, "repo-id"), repoIDFlag)
-	cmd.Flags().StringVar(&o.repoName, "repository", DefaultValue(ci, "repository"), repoNameFlag)
+	cmd.Flags().StringVar(&o.repoName, "repository", DefaultValue(ci, "repository"), attestationRepoNameFlag)
 	cmd.Flags().StringVar(&o.repoURL, "repo-url", DefaultValue(ci, "repo-url"), repoURLFlag)
 	cmd.Flags().StringVar(&o.repoProvider, "repo-provider", DefaultValue(ci, "repo-provider"), repoProviderFlag)
 	addFingerprintFlags(cmd, o.fingerprintOptions)

cmd/kosli/attestation.go

@@ -14,7 +14,10 @@ import (
 const commitDescription = `You can optionally associate the attestation to a git commit using ^--commit^ (requires access to a git repo).
 You can optionally redact some of the git commit data sent to Kosli using ^--redact-commit-info^.
 Note that when the attestation is reported for an artifact that does not yet exist in Kosli, ^--commit^ is required to facilitate
-binding the attestation to the right artifact.`
+binding the attestation to the right artifact.
+To record repository information, all three of ^--repo-id^, ^--repo-url^, and ^--repository^ must be set together.
+These are automatically set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps.
+In other CI systems, set them explicitly to capture repository metadata.`
 
 type URLInfo struct {
 	Href        string `json:"href"`

cmd/kosli/beginTrail.go

@@ -15,8 +15,11 @@ const beginTrailShortDesc = `Begin or update a Kosli flow trail.`
 
 const beginTrailLongDesc = beginTrailShortDesc + `
 
-You can optionally associate the trail to a git commit using ^--commit^ (requires access to a git repo). And you  
+You can optionally associate the trail to a git commit using ^--commit^ (requires access to a git repo). And you
 can optionally redact some of the git commit data sent to Kosli using ^--redact-commit-info^.
+To record repository information, all three of ^--repo-id^, ^--repo-url^, and ^--repository^ must be set together.
+These are automatically set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps.
+In other CI systems, set them explicitly to capture repository metadata.
 
 ^TRAIL-NAME^s must start with a letter or number, and only contain letters, numbers, ^.^, ^-^, ^_^, and ^~^.
 `
@@ -96,7 +99,7 @@ func newBeginTrailCmd(out io.Writer) *cobra.Command {
 	cmd.Flags().StringToStringVar(&o.externalFingerprints, "external-fingerprint", map[string]string{}, externalFingerprintFlag)
 	cmd.Flags().StringToStringVar(&o.externalURLs, "external-url", map[string]string{}, externalURLFlag)
 	cmd.Flags().StringVar(&o.repoID, "repo-id", DefaultValue(ci, "repo-id"), repoIDFlag)
-	cmd.Flags().StringVar(&o.repoName, "repository", DefaultValue(ci, "repository"), repoNameFlag)
+	cmd.Flags().StringVar(&o.repoName, "repository", DefaultValue(ci, "repository"), attestationRepoNameFlag)
 	cmd.Flags().StringVar(&o.repoURL, "repo-url", DefaultValue(ci, "repo-url"), repoURLFlag)
 	cmd.Flags().StringVar(&o.repoProvider, "repo-provider", DefaultValue(ci, "repo-provider"), repoProviderFlag)
 	addDryRunFlag(cmd)

cmd/kosli/flags.go

@@ -114,7 +114,7 @@ func addAttestationFlags(cmd *cobra.Command, o *CommonAttestationOptions, payloa
 	cmd.Flags().StringVar(&o.srcRepoRoot, "repo-root", ".", attestationRepoRootFlag)
 	cmd.Flags().StringVar(&payload.Description, "description", "", attestationDescription)
 	cmd.Flags().StringVar(&o.repoID, "repo-id", DefaultValue(ci, "repo-id"), repoIDFlag)
-	cmd.Flags().StringVar(&o.repoName, "repository", DefaultValue(ci, "repository"), repoNameFlag)
+	cmd.Flags().StringVar(&o.repoName, "repository", DefaultValue(ci, "repository"), attestationRepoNameFlag)
 	cmd.Flags().StringVar(&o.repoURL, "repo-url", DefaultValue(ci, "repo-url"), repoURLFlag)
 	cmd.Flags().StringVar(&o.repoProvider, "repo-provider", DefaultValue(ci, "repo-provider"), repoProviderFlag)
 

cmd/kosli/root.go

@@ -133,9 +133,9 @@ The ^.kosli_ignore^ will be treated as part of the artifact like any other file,
 	gitCommitFlag                   = "[defaulted] The git commit from which the artifact was created. (defaulted in some CIs: https://docs.kosli.com/ci-defaults, otherwise defaults to HEAD )."
 	buildUrlFlag                    = "The url of CI pipeline that built the artifact. (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
 	commitUrlFlag                   = "The url for the git commit that created the artifact. (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
-	repoIDFlag                      = "[optional] The unique identifier of the repository. (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
-	repoURLFlag                     = "[optional] The URL of the repository. Must be a valid URL if provided. (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
-	repoProviderFlag                = "[optional] The source code hosting provider. One of: github, gitlab, bitbucket, azure-devops."
+	repoIDFlag                      = "[conditional] The stable, unique identifier for the repository in your VCS provider (e.g. a numeric ID). Do not use the repository name as it can change if the repo is renamed. All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
+	repoURLFlag                     = "[conditional] The URL of the repository. Must be a valid URL. All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
+	repoProviderFlag                = "[optional] The source code hosting provider. One of: github, gitlab, bitbucket, azure-devops (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
 	bbUsernameFlag                  = "Bitbucket username. Only needed if you use --bitbucket-password"
 	bbPasswordFlag                  = "Bitbucket App password. See https://developer.atlassian.com/cloud/bitbucket/rest/intro/#authentication for more details."
 	bbAccessTokenFlag               = "Bitbucket repo/project/workspace access token. See https://developer.atlassian.com/cloud/bitbucket/rest/intro/#access-tokens for more details."
@@ -256,6 +256,7 @@ The ^.kosli_ignore^ will be treated as part of the artifact like any other file,
 	getAttestationFlowNameFlag      = "[conditional] The name of the Kosli flow for the attestation. Required if ATTESTATION-NAME provided. Cannot be used together with --attestation-id."
 	attestationIDFlag               = "[conditional] The unique identifier of the attestation to retrieve. Cannot be used together with ATTESTATION-NAME."
 	repoNameFlag                    = "[optional] The name of a git repo as it is registered in Kosli. e.g kosli-dev/cli"
+	attestationRepoNameFlag         = "[conditional] The name of the repository (e.g. owner/repo-name). All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: https://docs.kosli.com/ci-defaults )."
 )
 
 var global *GlobalOpts

cmd/kosli/testdata/output/docs/hugo/snyk.md

@@ -32,6 +32,9 @@ You can optionally associate the attestation to a git commit using `--commit` (r
 You can optionally redact some of the git commit data sent to Kosli using `--redact-commit-info`.
 Note that when the attestation is reported for an artifact that does not yet exist in Kosli, `--commit` is required to facilitate
 binding the attestation to the right artifact.
+To record repository information, all three of `--repo-id`, `--repo-url`, and `--repository` must be set together.
+These are automatically set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps.
+In other CI systems, set them explicitly to capture repository metadata.
 
 ## Flags
 | Flag | Description |
@@ -53,11 +56,11 @@ binding the attestation to the right artifact.
 |        --redact-commit-info strings  |  [optional] The list of commit info to be redacted before sending to Kosli. Allowed values are one or more of [author, message, branch].  |
 |        --registry-password string  |  [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry.  |
 |        --registry-username string  |  [conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry.  |
-|        --repo-id string  |  [optional] The unique identifier of the repository. (defaulted in some CIs: https://docs.kosli.com/ci-defaults ).  |
-|        --repo-provider string  |  [optional] The source code hosting provider. One of: github, gitlab, bitbucket, azure-devops.  |
+|        --repo-id string  |  [conditional] The stable, unique identifier for the repository in your VCS provider (e.g. a numeric ID). Do not use the repository name as it can change if the repo is renamed. All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: https://docs.kosli.com/ci-defaults ).  |
+|        --repo-provider string  |  [optional] The source code hosting provider. One of: github, gitlab, bitbucket, azure-devops (defaulted in some CIs: https://docs.kosli.com/ci-defaults ).  |
 |        --repo-root string  |  [defaulted] The directory where the source git repository is available. Only used if --commit is used or defaulted in CI, see https://docs.kosli.com/integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables . (default ".")  |
-|        --repo-url string  |  [optional] The URL of the repository. Must be a valid URL if provided. (defaulted in some CIs: https://docs.kosli.com/ci-defaults ).  |
-|        --repository string  |  [optional] The name of a git repo as it is registered in Kosli. e.g kosli-dev/cli  |
+|        --repo-url string  |  [conditional] The URL of the repository. Must be a valid URL. All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: https://docs.kosli.com/ci-defaults ).  |
+|        --repository string  |  [conditional] The name of the repository (e.g. owner/repo-name). All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: https://docs.kosli.com/ci-defaults ).  |
 |    -R, --scan-results string  |  The path to Snyk scan SARIF results file from 'snyk test' and 'snyk container test'. By default, the Snyk results will be uploaded to Kosli's evidence vault.  |
 |    -T, --trail string  |  The Kosli trail name.  |
 |        --upload-results  |  [defaulted] Whether to upload the provided Snyk results file as an attachment to Kosli or not. (default true)  |

cmd/kosli/testdata/output/docs/mintlify/snyk.md

@@ -30,6 +30,9 @@ You can optionally associate the attestation to a git commit using `--commit` (r
 You can optionally redact some of the git commit data sent to Kosli using `--redact-commit-info`.
 Note that when the attestation is reported for an artifact that does not yet exist in Kosli, `--commit` is required to facilitate
 binding the attestation to the right artifact.
+To record repository information, all three of `--repo-id`, `--repo-url`, and `--repository` must be set together.
+These are automatically set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps.
+In other CI systems, set them explicitly to capture repository metadata.
 
 ## Flags
 | Flag | Description |
@@ -51,11 +54,11 @@ binding the attestation to the right artifact.
 |        --redact-commit-info strings  |  [optional] The list of commit info to be redacted before sending to Kosli. Allowed values are one or more of [author, message, branch].  |
 |        --registry-password string  |  [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry.  |
 |        --registry-username string  |  [conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry.  |
-|        --repo-id string  |  [optional] The unique identifier of the repository. (defaulted in some CIs: [docs](/ci-defaults) ).  |
-|        --repo-provider string  |  [optional] The source code hosting provider. One of: github, gitlab, bitbucket, azure-devops.  |
+|        --repo-id string  |  [conditional] The stable, unique identifier for the repository in your VCS provider (e.g. a numeric ID). Do not use the repository name as it can change if the repo is renamed. All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: [docs](/ci-defaults) ).  |
+|        --repo-provider string  |  [optional] The source code hosting provider. One of: github, gitlab, bitbucket, azure-devops (defaulted in some CIs: [docs](/ci-defaults) ).  |
 |        --repo-root string  |  [defaulted] The directory where the source git repository is available. Only used if --commit is used or defaulted in CI, see [docs](/integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables) . (default ".")  |
-|        --repo-url string  |  [optional] The URL of the repository. Must be a valid URL if provided. (defaulted in some CIs: [docs](/ci-defaults) ).  |
-|        --repository string  |  [optional] The name of a git repo as it is registered in Kosli. e.g kosli-dev/cli  |
+|        --repo-url string  |  [conditional] The URL of the repository. Must be a valid URL. All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: [docs](/ci-defaults) ).  |
+|        --repository string  |  [conditional] The name of the repository (e.g. owner/repo-name). All three of --repo-id, --repo-url and --repository must be set to record repository information (defaulted in some CIs: [docs](/ci-defaults) ).  |
 |    -R, --scan-results string  |  The path to Snyk scan SARIF results file from 'snyk test' and 'snyk container test'. By default, the Snyk results will be uploaded to Kosli's evidence vault.  |
 |    -T, --trail string  |  The Kosli trail name.  |
 |        --upload-results  |  [defaulted] Whether to upload the provided Snyk results file as an attachment to Kosli or not. (default true)  |