diff --git a/cmd/kosli/attestArtifact.go b/cmd/kosli/attestArtifact.go index 5ac7e60fa..1750bd4ff 100644 --- a/cmd/kosli/attestArtifact.go +++ b/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) diff --git a/cmd/kosli/attestation.go b/cmd/kosli/attestation.go index 9736dae93..9a8240231 100644 --- a/cmd/kosli/attestation.go +++ b/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"` diff --git a/cmd/kosli/beginTrail.go b/cmd/kosli/beginTrail.go index b8a90791d..478e2997e 100644 --- a/cmd/kosli/beginTrail.go +++ b/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) diff --git a/cmd/kosli/flags.go b/cmd/kosli/flags.go index 067912b8b..4b42f3bd5 100644 --- a/cmd/kosli/flags.go +++ b/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) diff --git a/cmd/kosli/root.go b/cmd/kosli/root.go index 4b786b53c..171ee6215 100644 --- a/cmd/kosli/root.go +++ b/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 diff --git a/cmd/kosli/testdata/output/docs/hugo/snyk.md b/cmd/kosli/testdata/output/docs/hugo/snyk.md index 9c376ab4a..8ccdc9afa 100644 --- a/cmd/kosli/testdata/output/docs/hugo/snyk.md +++ b/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) | diff --git a/cmd/kosli/testdata/output/docs/mintlify/snyk.md b/cmd/kosli/testdata/output/docs/mintlify/snyk.md index b91fb9ee3..28f46d1e7 100644 --- a/cmd/kosli/testdata/output/docs/mintlify/snyk.md +++ b/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) |