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

@@ -132,9 +132,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."
@@ -255,6 +255,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