From 929e5f762fca76989fbe017d1aafcacfe6b8f543 Mon Sep 17 00:00:00 2001 From: Narthana Epa Date: Wed, 23 Aug 2023 14:17:10 +1000 Subject: [PATCH 1/2] Adjust cli help output to work better with documentation generation I've adjusted the documentation generation with some new feature. The biggest is that text that is indented by 4 spaces is treated as a code block. So we need to unindent non-code and indent code. --- clicommand/acknowledgements.go | 10 ++-- clicommand/agent_start.go | 14 +++--- clicommand/annotate.go | 40 ++++++++-------- clicommand/annotation_remove.go | 12 ++--- clicommand/artifact_download.go | 42 ++++++++-------- clicommand/artifact_search.go | 82 ++++++++++++++++---------------- clicommand/artifact_shasum.go | 40 ++++++++-------- clicommand/artifact_upload.go | 68 +++++++++++++------------- clicommand/bootstrap.go | 28 ++++++----- clicommand/env_dump.go | 9 ++-- clicommand/env_get.go | 64 ++++++++++++------------- clicommand/env_set.go | 32 +++++++------ clicommand/env_unset.go | 29 +++++------ clicommand/lock_acquire.go | 28 +++++------ clicommand/lock_do.go | 35 +++++++------- clicommand/lock_done.go | 21 ++++---- clicommand/lock_get.go | 21 ++++---- clicommand/lock_release.go | 23 ++++----- clicommand/meta_data_exists.go | 8 ++-- clicommand/meta_data_get.go | 6 +-- clicommand/meta_data_keys.go | 8 ++-- clicommand/meta_data_set.go | 18 +++---- clicommand/oidc_request_token.go | 21 ++++---- clicommand/pipeline_upload.go | 44 ++++++++--------- clicommand/step_get.go | 20 ++++---- clicommand/step_update.go | 32 ++++++------- main.go | 14 +++--- 27 files changed, 391 insertions(+), 378 deletions(-) diff --git a/clicommand/acknowledgements.go b/clicommand/acknowledgements.go index b2f92de6b7..1890adb925 100644 --- a/clicommand/acknowledgements.go +++ b/clicommand/acknowledgements.go @@ -10,15 +10,17 @@ import ( ) const acknowledgementsHelpDescription = `Usage: - buildkite-agent acknowledgements + + buildkite-agent acknowledgements Description: - Prints the licenses and notices of open source software incorporated into - this software. + +Prints the licenses and notices of open source software incorporated into +this software. Example: - $ buildkite-agent acknowledgements` + $ buildkite-agent acknowledgements` //go:embed *.md.gz var files embed.FS diff --git a/clicommand/agent_start.go b/clicommand/agent_start.go index 8afcd80f01..90e90bf34d 100644 --- a/clicommand/agent_start.go +++ b/clicommand/agent_start.go @@ -39,20 +39,20 @@ import ( const startDescription = `Usage: - buildkite-agent start [options...] + buildkite-agent start [options...] Description: - When a job is ready to run it will call the "bootstrap-script" - and pass it all the environment variables required for the job to run. - This script is responsible for checking out the code, and running the - actual build script defined in the pipeline. +When a job is ready to run it will call the "bootstrap-script" +and pass it all the environment variables required for the job to run. +This script is responsible for checking out the code, and running the +actual build script defined in the pipeline. - The agent will run any jobs within a PTY (pseudo terminal) if available. +The agent will run any jobs within a PTY (pseudo terminal) if available. Example: - $ buildkite-agent start --token xxx` + $ buildkite-agent start --token xxx` var verificationFailureBehaviors = []string{agent.VerificationBehaviourBlock, agent.VerificationBehaviourWarn} diff --git a/clicommand/annotate.go b/clicommand/annotate.go index 0458ca5500..99e652aa45 100644 --- a/clicommand/annotate.go +++ b/clicommand/annotate.go @@ -21,37 +21,37 @@ const ( const annotateHelpDescription = `Usage: - buildkite-agent annotate [body] [options...] + buildkite-agent annotate [body] [options...] Description: - Build annotations allow you to customize the Buildkite build interface to - show information that may surface from your builds. Some examples include: +Build annotations allow you to customize the Buildkite build interface to +show information that may surface from your builds. Some examples include: - - Links to artifacts generated by your jobs - - Test result summaries - - Graphs that include analysis about your codebase - - Helpful information for team members about what happened during a build +- Links to artifacts generated by your jobs +- Test result summaries +- Graphs that include analysis about your codebase +- Helpful information for team members about what happened during a build - Annotations are written in CommonMark-compliant Markdown, with "GitHub - Flavored Markdown" extensions. +Annotations are written in CommonMark-compliant Markdown, with "GitHub +Flavored Markdown" extensions. - The annotation body can be supplied as a command line argument, or by piping - content into the command. The maximum size of each annotation body is 1MiB. +The annotation body can be supplied as a command line argument, or by piping +content into the command. The maximum size of each annotation body is 1MiB. - You can update an existing annotation's body by running the annotate command - again and provide the same context as the one you want to update. Or if you - leave context blank, it will use the default context. +You can update an existing annotation's body by running the annotate command +again and provide the same context as the one you want to update. Or if you +leave context blank, it will use the default context. - You can also update only the style of an existing annotation by omitting the - body entirely and providing a new style value. +You can also update only the style of an existing annotation by omitting the +body entirely and providing a new style value. Example: - $ buildkite-agent annotate "All tests passed! :rocket:" - $ cat annotation.md | buildkite-agent annotate --style "warning" - $ buildkite-agent annotate --style "success" --context "junit" - $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success"` + $ buildkite-agent annotate "All tests passed! :rocket:" + $ cat annotation.md | buildkite-agent annotate --style "warning" + $ buildkite-agent annotate --style "success" --context "junit" + $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success"` type AnnotateConfig struct { Body string `cli:"arg:0" label:"annotation body"` diff --git a/clicommand/annotation_remove.go b/clicommand/annotation_remove.go index 9211d98f68..a5daff744d 100644 --- a/clicommand/annotation_remove.go +++ b/clicommand/annotation_remove.go @@ -11,19 +11,19 @@ import ( const annotationRemoveHelpDescription = `Usage: - buildkite-agent annotation remove [arguments...] + buildkite-agent annotation remove [arguments...] Description: - Remove an existing annotation which was previously published using the - buildkite-agent annotate command. +Remove an existing annotation which was previously published using the +buildkite-agent annotate command. - If you leave context blank, it will use the default context. +If you leave context blank, it will use the default context. Example: - $ buildkite-agent annotation remove - $ buildkite-agent annotation remove --context "remove-me"` + $ buildkite-agent annotation remove + $ buildkite-agent annotation remove --context "remove-me"` type AnnotationRemoveConfig struct { Context string `cli:"context" validate:"required"` diff --git a/clicommand/artifact_download.go b/clicommand/artifact_download.go index c507dc8438..f8c82ff361 100644 --- a/clicommand/artifact_download.go +++ b/clicommand/artifact_download.go @@ -10,40 +10,40 @@ import ( const downloadHelpDescription = `Usage: - buildkite-agent artifact download [options] + buildkite-agent artifact download [options] Description: - Downloads artifacts matching from Buildkite to - directory on the local machine. +Downloads artifacts matching from Buildkite to +directory on the local machine. - Note: You need to ensure that your search query is surrounded by quotes if - using a wild card as the built-in shell path globbing will expand the wild - card and break the query. +Note: You need to ensure that your search query is surrounded by quotes if +using a wild card as the built-in shell path globbing will expand the wild +card and break the query. - If the last path component of matches the first path component - of your , the last component of is dropped from the - final path. For example, a query of 'app/logs/*' with a destination of - 'foo/app' will write any matched artifact files to 'foo/app/logs/', relative - to the current working directory. +If the last path component of matches the first path component +of your , the last component of is dropped from the +final path. For example, a query of 'app/logs/*' with a destination of +'foo/app' will write any matched artifact files to 'foo/app/logs/', relative +to the current working directory. - You can also change working directory to the intended destination and use a - of '.' to always create a directory hierarchy matching the - artifact paths. +You can also change working directory to the intended destination and use a + of '.' to always create a directory hierarchy matching the +artifact paths. Example: - $ buildkite-agent artifact download "pkg/*.tar.gz" . --build xxx + $ buildkite-agent artifact download "pkg/*.tar.gz" . --build xxx - This will search across all the artifacts for the build with files that match that part. - The first argument is the search query, and the second argument is the download destination. +This will search across all the artifacts for the build with files that match that part. +The first argument is the search query, and the second argument is the download destination. - If you're trying to download a specific file, and there are multiple artifacts from different - jobs, you can target the particular job you want to download the artifact from: +If you're trying to download a specific file, and there are multiple artifacts from different +jobs, you can target the particular job you want to download the artifact from: - $ buildkite-agent artifact download "pkg/*.tar.gz" . --step "tests" --build xxx + $ buildkite-agent artifact download "pkg/*.tar.gz" . --step "tests" --build xxx - You can also use the step's jobs id (provided by the environment variable $BUILDKITE_JOB_ID)` +You can also use the step's jobs id (provided by the environment variable $BUILDKITE_JOB_ID)` type ArtifactDownloadConfig struct { Query string `cli:"arg:0" label:"artifact search query" validate:"required"` diff --git a/clicommand/artifact_search.go b/clicommand/artifact_search.go index 3f7b072161..685074510f 100644 --- a/clicommand/artifact_search.go +++ b/clicommand/artifact_search.go @@ -14,35 +14,57 @@ import ( const searchHelpDescription = `Usage: - buildkite-agent artifact search [options] + buildkite-agent artifact search [options] Description: - Searches for build artifacts specified by on Buildkite +Searches for build artifacts specified by on Buildkite - Note: You need to ensure that your search query is surrounded by quotes if - using a wild card as the built-in shell path globbing will provide files, - which will break the search. +Note: You need to ensure that your search query is surrounded by quotes if +using a wild card as the built-in shell path globbing will provide files, +which will break the search. Example: - $ buildkite-agent artifact search "pkg/*.tar.gz" --build xxx + $ buildkite-agent artifact search "pkg/*.tar.gz" --build xxx - This will search across all uploaded artifacts in a build for files that match that query. - The first argument is the search query. +This will search across all uploaded artifacts in a build for files that match that query. +The first argument is the search query. - If you're trying to find a specific file, and there are multiple artifacts from different - jobs, you can target the particular job you want to search the artifacts from using --step: +If you're trying to find a specific file, and there are multiple artifacts from different +jobs, you can target the particular job you want to search the artifacts from using --step: - $ buildkite-agent artifact search "pkg/*.tar.gz" --step "tests" --build xxx + $ buildkite-agent artifact search "pkg/*.tar.gz" --step "tests" --build xxx - You can also use the step's job id (provided by the environment variable $BUILDKITE_JOB_ID) +You can also use the step's job id (provided by the environment variable $BUILDKITE_JOB_ID) - Output formatting can be altered with the -format flag as follows: +Output formatting can be altered with the -format flag as follows: - $ buildkite-agent artifact search "*" -format "%p\n" + $ buildkite-agent artifact search "*" -format "%p\n" - The above will return a list of filenames separated by newline.` +The above will return a list of filenames separated by newline.` + +const artifactSearchHelpTemplate = `{{.Description}} + +Options: + +{{range .VisibleFlags}} {{.}} +{{end}} +Format specifiers: + + %i UUID of the artifact + + %p Artifact path + + %c Artifact creation time (an ISO 8601 / RFC-3339 formatted UTC timestamp) + + %j UUID of the job that uploaded the artifact, helpful for subsequent artifact downloads + + %s File size of the artifact in bytes + + %S SHA1 checksum of the artifact + + %u Download URL for the artifact, though consider using 'buildkite-agent artifact download' instead` type ArtifactSearchConfig struct { Query string `cli:"arg:0" label:"artifact search query" validate:"required"` @@ -67,32 +89,10 @@ type ArtifactSearchConfig struct { } var ArtifactSearchCommand = cli.Command{ - Name: "search", - Usage: "Searches artifacts in Buildkite", - Description: searchHelpDescription, - CustomHelpTemplate: `{{.Description}} - -Options: - - {{range .VisibleFlags}}{{.}} - {{end}} - -Format specifiers: - - %i UUID of the artifact - - %p Artifact path - - %c Artifact creation time (an ISO 8601 / RFC-3339 formatted UTC timestamp) - - %j UUID of the job that uploaded the artifact, helpful for subsequent artifact downloads - - %s File size of the artifact in bytes - - %S SHA1 checksum of the artifact - - %u Download URL for the artifact, though consider using 'buildkite-agent artifact download' instead -`, + Name: "search", + Usage: "Searches artifacts in Buildkite", + Description: searchHelpDescription, + CustomHelpTemplate: artifactSearchHelpTemplate, Flags: []cli.Flag{ cli.StringFlag{ Name: "step", diff --git a/clicommand/artifact_shasum.go b/clicommand/artifact_shasum.go index d87dd1dbca..2bf26bc866 100644 --- a/clicommand/artifact_shasum.go +++ b/clicommand/artifact_shasum.go @@ -14,40 +14,40 @@ import ( const shasumHelpDescription = `Usage: - buildkite-agent artifact shasum [options...] + buildkite-agent artifact shasum [options...] Description: - Prints the SHA-1 or SHA-256 hash for the single artifact specified by a - search query. +Prints the SHA-1 or SHA-256 hash for the single artifact specified by a +search query. - The hash is fetched from Buildkite's API, having been generated client-side - by the agent during artifact upload. +The hash is fetched from Buildkite's API, having been generated client-side +by the agent during artifact upload. - A search query that does not match exactly one artifact results in an error. +A search query that does not match exactly one artifact results in an error. - Note: You need to ensure that your search query is surrounded by quotes if - using a wild card as the built-in shell path globbing will provide files, - which will break the download. +Note: You need to ensure that your search query is surrounded by quotes if +using a wild card as the built-in shell path globbing will provide files, +which will break the download. Example: - $ buildkite-agent artifact shasum "pkg/release.tar.gz" --build xxx + $ buildkite-agent artifact shasum "pkg/release.tar.gz" --build xxx - This will search for all files in the build with path "pkg/release.tar.gz", - and if exactly one match is found, the SHA-1 hash generated during upload - is printed. +This will search for all files in the build with path "pkg/release.tar.gz", +and if exactly one match is found, the SHA-1 hash generated during upload +is printed. - If you would like to target artifacts from a specific build step, you can do - so by using the --step argument. +If you would like to target artifacts from a specific build step, you can do +so by using the --step argument. - $ buildkite-agent artifact shasum "pkg/release.tar.gz" --step "release" --build xxx + $ buildkite-agent artifact shasum "pkg/release.tar.gz" --step "release" --build xxx - You can also use the step's job ID (provided by the environment variable $BUILDKITE_JOB_ID) +You can also use the step's job ID (provided by the environment variable $BUILDKITE_JOB_ID) - The --sha256 argument requests SHA-256 instead of SHA-1; this is only - available for artifacts uploaded since SHA-256 support was added to the - agent.` +The ′--sha256′ argument requests SHA-256 instead of SHA-1; this is only +available for artifacts uploaded since SHA-256 support was added to the +agent.` type ArtifactShasumConfig struct { Query string `cli:"arg:0" label:"artifact search query" validate:"required"` diff --git a/clicommand/artifact_upload.go b/clicommand/artifact_upload.go index 7f07b800e2..53cb58fdd0 100644 --- a/clicommand/artifact_upload.go +++ b/clicommand/artifact_upload.go @@ -10,60 +10,60 @@ import ( const uploadHelpDescription = `Usage: - buildkite-agent artifact upload [options] [destination] + buildkite-agent artifact upload [options] [destination] Description: - Uploads files to a job as artifacts. +Uploads files to a job as artifacts. - You need to ensure that the paths are surrounded by quotes otherwise the - built-in shell path globbing will provide the files, which is currently not - supported. +You need to ensure that the paths are surrounded by quotes otherwise the +built-in shell path globbing will provide the files, which is currently not +supported. - You can specify an alternate destination on Amazon S3, Google Cloud Storage - or Artifactory as per the examples below. This may be specified in the - 'destination' argument, or in the 'BUILDKITE_ARTIFACT_UPLOAD_DESTINATION' - environment variable. Otherwise, artifacts are uploaded to a - Buildkite-managed Amazon S3 bucket, where they’re retained for six months. +You can specify an alternate destination on Amazon S3, Google Cloud Storage +or Artifactory as per the examples below. This may be specified in the +'destination' argument, or in the 'BUILDKITE_ARTIFACT_UPLOAD_DESTINATION' +environment variable. Otherwise, artifacts are uploaded to a +Buildkite-managed Amazon S3 bucket, where they’re retained for six months. Example: - $ buildkite-agent artifact upload "log/**/*.log" + $ buildkite-agent artifact upload "log/**/*.log" - You can also upload directly to Amazon S3 if you'd like to host your own artifacts: +You can also upload directly to Amazon S3 if you'd like to host your own artifacts: - $ export BUILDKITE_S3_ACCESS_KEY_ID=xxx - $ export BUILDKITE_S3_SECRET_ACCESS_KEY=yyy - $ export BUILDKITE_S3_DEFAULT_REGION=eu-central-1 # default is us-east-1 - $ export BUILDKITE_S3_ACL=private # default is public-read - $ buildkite-agent artifact upload "log/**/*.log" s3://name-of-your-s3-bucket/$BUILDKITE_JOB_ID + $ export BUILDKITE_S3_ACCESS_KEY_ID=xxx + $ export BUILDKITE_S3_SECRET_ACCESS_KEY=yyy + $ export BUILDKITE_S3_DEFAULT_REGION=eu-central-1 # default is us-east-1 + $ export BUILDKITE_S3_ACL=private # default is public-read + $ buildkite-agent artifact upload "log/**/*.log" s3://name-of-your-s3-bucket/$BUILDKITE_JOB_ID - You can use Amazon IAM assumed roles by specifying the session token: +You can use Amazon IAM assumed roles by specifying the session token: - $ export BUILDKITE_S3_SESSION_TOKEN=zzz + $ export BUILDKITE_S3_SESSION_TOKEN=zzz - Or upload directly to Google Cloud Storage: +Or upload directly to Google Cloud Storage: - $ export BUILDKITE_GS_ACL=private - $ buildkite-agent artifact upload "log/**/*.log" gs://name-of-your-gs-bucket/$BUILDKITE_JOB_ID + $ export BUILDKITE_GS_ACL=private + $ buildkite-agent artifact upload "log/**/*.log" gs://name-of-your-gs-bucket/$BUILDKITE_JOB_ID - Or upload directly to Artifactory: +Or upload directly to Artifactory: - $ export BUILDKITE_ARTIFACTORY_URL=http://my-artifactory-instance.com/artifactory - $ export BUILDKITE_ARTIFACTORY_USER=carol-danvers - $ export BUILDKITE_ARTIFACTORY_PASSWORD=xxx - $ buildkite-agent artifact upload "log/**/*.log" rt://name-of-your-artifactory-repo/$BUILDKITE_JOB_ID + $ export BUILDKITE_ARTIFACTORY_URL=http://my-artifactory-instance.com/artifactory + $ export BUILDKITE_ARTIFACTORY_USER=carol-danvers + $ export BUILDKITE_ARTIFACTORY_PASSWORD=xxx + $ buildkite-agent artifact upload "log/**/*.log" rt://name-of-your-artifactory-repo/$BUILDKITE_JOB_ID - By default, symlinks to directories will not be explored when resolving the glob, but symlinks to files will be uploaded as the linked files. - To ignore symlinks to files use: +By default, symlinks to directories will not be explored when resolving the glob, but symlinks to +files will be uploaded as the linked files. To ignore symlinks to files use: - $ buildkite-agent artifact upload --upload-skip-symlinks "log/**/*.log" + $ buildkite-agent artifact upload --upload-skip-symlinks "log/**/*.log" - Note: uploading symlinks to files without following them is not supported. - If you need to preserve them in a directory, we recommend creating a tar archive: +Note: uploading symlinks to files without following them is not supported. +If you need to preserve them in a directory, we recommend creating a tar archive: - $ tar -cvf log.tar log/**/* - $ buildkite-agent upload log.tar` + $ tar -cvf log.tar log/**/* + $ buildkite-agent upload log.tar` type ArtifactUploadConfig struct { UploadPaths string `cli:"arg:0" label:"upload paths" validate:"required"` diff --git a/clicommand/bootstrap.go b/clicommand/bootstrap.go index a15af5034d..4f82758862 100644 --- a/clicommand/bootstrap.go +++ b/clicommand/bootstrap.go @@ -16,29 +16,31 @@ import ( const bootstrapHelpDescription = `Usage: - buildkite-agent bootstrap [options...] + buildkite-agent bootstrap [options...] Description: - The bootstrap command executes a Buildkite job locally. +The bootstrap command executes a Buildkite job locally. - Generally the bootstrap command is run as a sub-process of the buildkite-agent to execute - a given job sent from buildkite.com, but you can also invoke the bootstrap manually. +Generally the bootstrap command is run as a sub-process of the buildkite-agent to execute +a given job sent from buildkite.com, but you can also invoke the bootstrap manually. - Execution is broken down into phases. By default, the bootstrap runs a plugin phase which - sets up any plugins specified, then a checkout phase which pulls down your code and then a - command phase that executes the specified command in the created environment. +Execution is broken down into phases. By default, the bootstrap runs a plugin phase which +sets up any plugins specified, then a checkout phase which pulls down your code and then a +command phase that executes the specified command in the created environment. - You can run only specific phases with the --phases flag. +You can run only specific phases with the --phases flag. - The bootstrap is also responsible for executing hooks around the phases. - See https://buildkite.com/docs/agent/v3/hooks for more details. +The bootstrap is also responsible for executing hooks around the phases. +See https://buildkite.com/docs/agent/v3/hooks for more details. Example: - $ eval $(curl -s -H "Authorization: Bearer xxx" \ - "https://api.buildkite.com/v2/organizations/[org]/pipelines/[proj]/builds/[build]/jobs/[job]/env.txt" | sed 's/^/export /') - $ buildkite-agent bootstrap --build-path builds` + $ eval $(curl -s -H "Authorization: Bearer xxx" \ + "https://api.buildkite.com/v2/organizations/[org]/pipelines/[proj]/builds/[build]/jobs/[job]/env.txt" | \ + sed 's/^/export /' \ + ) + $ buildkite-agent bootstrap --build-path builds` type BootstrapConfig struct { Command string `cli:"command"` diff --git a/clicommand/env_dump.go b/clicommand/env_dump.go index 0e0ccf099a..11ba5ed090 100644 --- a/clicommand/env_dump.go +++ b/clicommand/env_dump.go @@ -10,12 +10,13 @@ import ( const envDumpHelpDescription = `Usage: - buildkite-agent env dump [options] +buildkite-agent env dump [options] Description: - Prints out the environment of the current process as a JSON object, easily - parsable by other programs. Used when executing hooks to discover changes - that hooks make to the environment. + +Prints out the environment of the current process as a JSON object, easily +parsable by other programs. Used when executing hooks to discover changes +that hooks make to the environment. Example: diff --git a/clicommand/env_get.go b/clicommand/env_get.go index 8ea870aae4..eb2f2133a8 100644 --- a/clicommand/env_get.go +++ b/clicommand/env_get.go @@ -13,54 +13,54 @@ import ( const envClientErrMessage = `Could not create Job API client: %v This command can only be used from hooks or plugins running under a job executor -where the "job-api" experiment is enabled. -` +where the "job-api" experiment is enabled.` const envGetHelpDescription = `Usage: - buildkite-agent env get [variables] + buildkite-agent env get [variables] Description: - Retrieves environment variables and their current values from the current job - execution environment. - Note that this subcommand is only available from within the job executor with - the ′job-api′ experiment enabled. +Retrieves environment variables and their current values from the current job +execution environment. - Changes to the job environment only apply to the environments of subsequent - phases of the job. However, ′env get′ can be used to inspect the changes made - with ′env set′ and ′env unset′. +Note that this subcommand is only available from within the job executor with +the ′job-api′ experiment enabled. + +Changes to the job environment only apply to the environments of subsequent +phases of the job. However, ′env get′ can be used to inspect the changes made +with ′env set′ and ′env unset′. Examples: - Getting all variables in key=value format: - $ buildkite-agent env get - ALPACA=Geronimo the Incredible - BUILDKITE=true - LLAMA=Kuzco - ... +Getting all variables in key=value format: + + $ buildkite-agent env get + ALPACA=Geronimo the Incredible + BUILDKITE=true + LLAMA=Kuzco + ... - Getting the value of one variable: +Getting the value of one variable: - $ buildkite-agent env get LLAMA - Kuzco + $ buildkite-agent env get LLAMA + Kuzco - Getting multiple specific variables: +Getting multiple specific variables: - $ buildkite-agent env get LLAMA ALPACA - ALPACA=Geronimo the Incredible - LLAMA=Kuzco + $ buildkite-agent env get LLAMA ALPACA + ALPACA=Geronimo the Incredible + LLAMA=Kuzco - Getting variables as a JSON object: +Getting variables as a JSON object: - $ buildkite-agent env get --format=json-pretty - { - "ALPACA": "Geronimo the Incredible", - "BUILDKITE": "true", - "LLAMA": "Kuzco", - ... - } -` + $ buildkite-agent env get --format=json-pretty + { + "ALPACA": "Geronimo the Incredible", + "BUILDKITE": "true", + "LLAMA": "Kuzco", + ... + }` type EnvGetConfig struct { Format string `cli:"format"` diff --git a/clicommand/env_set.go b/clicommand/env_set.go index 1fb7f32b0e..3af790665d 100644 --- a/clicommand/env_set.go +++ b/clicommand/env_set.go @@ -14,30 +14,32 @@ import ( const envSetHelpDescription = `Usage: - buildkite-agent env set [variable] + buildkite-agent env set [variable] Description: - Sets environment variables in the current job execution environment. - Changes to the job environment variables only apply to subsequent phases of the job. - This command cannot unset Buildkite read-only variables. - To read the new values of variables from within the current phase, use ′env get′. +Sets environment variables in the current job execution environment. +Changes to the job environment variables only apply to subsequent phases of the job. +This command cannot unset Buildkite read-only variables. - Note that this subcommand is only available from within the job executor with the job-api experiment enabled. +To read the new values of variables from within the current phase, use ′env get′. + +Note that this subcommand is only available from within the job executor with the job-api experiment enabled. Examples: - Setting the variables ′LLAMA′ and ′ALPACA′: - $ buildkite-agent env set LLAMA=Kuzco "ALPACA=Geronimo the Incredible" - Added: - + LLAMA - Updated: - ~ ALPACA +Setting the variables ′LLAMA′ and ′ALPACA′: + + $ buildkite-agent env set LLAMA=Kuzco "ALPACA=Geronimo the Incredible" + Added: + + LLAMA + Updated: + ~ ALPACA - Setting the variables ′LLAMA′ and ′ALPACA′ using a JSON object supplied over standard input: +Setting the variables ′LLAMA′ and ′ALPACA′ using a JSON object supplied over standard input: - $ echo '{"ALPACA":"Geronimo the Incredible","LLAMA":"Kuzco"}' | buildkite-agent env set --input-format=json --output-format=quiet - -` + $ echo '{"ALPACA":"Geronimo the Incredible","LLAMA":"Kuzco"}' | \ + buildkite-agent env set --input-format=json --output-format=quiet -` type EnvSetConfig struct { InputFormat string `cli:"input-format"` diff --git a/clicommand/env_unset.go b/clicommand/env_unset.go index df067f8e05..9fe125e444 100644 --- a/clicommand/env_unset.go +++ b/clicommand/env_unset.go @@ -13,30 +13,31 @@ import ( const envUnsetHelpDescription = `Usage: - buildkite-agent env unset [variables] + buildkite-agent env unset [variables] Description: - Unsets environment variables in the current job execution environment. - Changes to the job environment variables only apply to subsequent phases of the job. - This command cannot unset Buildkite read-only variables. - To read the new values of variables from within the current phase, use ′env get′. +Unsets environment variables in the current job execution environment. +Changes to the job environment variables only apply to subsequent phases of the job. +This command cannot unset Buildkite read-only variables. - Note that this subcommand is only available from within the job executor with the job-api experiment enabled. +To read the new values of variables from within the current phase, use ′env get′. + +Note that this subcommand is only available from within the job executor with the job-api experiment enabled. Examples: - Unsetting the variables ′LLAMA′ and ′ALPACA′: +Unsetting the variables ′LLAMA′ and ′ALPACA′: - $ buildkite-agent env unset LLAMA ALPACA - Unset: - - ALPACA - - LLAMA + $ buildkite-agent env unset LLAMA ALPACA + Unset: + - ALPACA + - LLAMA - Unsetting the variables ′LLAMA′ and ′ALPACA′ with a JSON list supplied over standard input +Unsetting the variables ′LLAMA′ and ′ALPACA′ with a JSON list supplied over standard input - $ echo '["LLAMA","ALPACA"]' | buildkite-agent env unset --input-format=json --output-format=quiet - -` + $ echo '["LLAMA","ALPACA"]' | \ + buildkite-agent env unset --input-format=json --output-format=quiet -` type EnvUnsetConfig struct { InputFormat string `cli:"input-format"` diff --git a/clicommand/lock_acquire.go b/clicommand/lock_acquire.go index 3b6b947d27..da22ae70f2 100644 --- a/clicommand/lock_acquire.go +++ b/clicommand/lock_acquire.go @@ -12,27 +12,27 @@ import ( const lockAcquireHelpDescription = `Usage: - buildkite-agent lock acquire [key] + buildkite-agent lock acquire [key] Description: - Acquires the lock for the given key. ′lock acquire′ will wait (potentially - forever) until it can acquire the lock, if the lock is already held by - another process. If multiple processes are waiting for the same lock, there - is no ordering guarantee of which one will be given the lock next. - To prevent separate processes unlocking each other, the output from ′lock - acquire′ should be stored, and passed to ′lock release′. +Acquires the lock for the given key. ′lock acquire′ will wait (potentially +forever) until it can acquire the lock, if the lock is already held by +another process. If multiple processes are waiting for the same lock, there +is no ordering guarantee of which one will be given the lock next. - Note that this subcommand is only available when an agent has been started - with the ′agent-api′ experiment enabled. +To prevent separate processes unlocking each other, the output from ′lock +acquire′ should be stored, and passed to ′lock release′. -Examples: +Note that this subcommand is only available when an agent has been started +with the ′agent-api′ experiment enabled. - $ token=$(buildkite-agent lock acquire llama) - $ critical_section() - $ buildkite-agent lock release llama "${token}" +Examples: -` + #!/bin/bash + token=$(buildkite-agent lock acquire llama) + # your critical section here... + buildkite-agent lock release llama "${token}"` type LockAcquireConfig struct { // Common config options diff --git a/clicommand/lock_do.go b/clicommand/lock_do.go index e9d713aafe..ca2e8d2e5f 100644 --- a/clicommand/lock_do.go +++ b/clicommand/lock_do.go @@ -12,31 +12,32 @@ import ( const lockDoHelpDescription = `Usage: - buildkite-agent lock do [key] + buildkite-agent lock do [key] Description: - Begins a do-once lock. Do-once can be used by multiple processes to - wait for completion of some shared work, where only one process should do - the work. - Note that this subcommand is only available when an agent has been started - with the ′agent-api′ experiment enabled. +Begins a do-once lock. Do-once can be used by multiple processes to +wait for completion of some shared work, where only one process should do +the work. - ′lock do′ will do one of two things: +Note that this subcommand is only available when an agent has been started +with the ′agent-api′ experiment enabled. - - Print 'do'. The calling process should proceed to do the work and then - call ′lock done′. - - Wait until the work is marked as done (with ′lock done′) and print 'done'. +′lock do′ will do one of two things: - If ′lock do′ prints 'done' immediately, the work was already done. +- Print 'do'. The calling process should proceed to do the work and then + call ′lock done′. +- Wait until the work is marked as done (with ′lock done′) and print 'done'. + +If ′lock do′ prints 'done' immediately, the work was already done. Examples: - #!/bin/bash - if [[ $(buildkite-agent lock do llama) == 'do' ]]; then - # your critical section here... - buildkite-agent lock done llama - fi` + #!/bin/bash + if [[ $(buildkite-agent lock do llama) == 'do' ]]; then + # your critical section here... + buildkite-agent lock done llama + fi` type LockDoConfig struct { // Common config options @@ -58,7 +59,7 @@ func lockDoFlags() []cli.Flag { []cli.Flag{ cli.DurationFlag{ Name: "lock-wait-timeout", - Usage: "If specified, sets a maximum duration to wait for a lock before giving up", + Usage: "Sets a maximum duration to wait for a lock before giving up", EnvVar: "BUILDKITE_LOCK_WAIT_TIMEOUT", }, }, diff --git a/clicommand/lock_done.go b/clicommand/lock_done.go index da048c48b3..663866e2b0 100644 --- a/clicommand/lock_done.go +++ b/clicommand/lock_done.go @@ -11,22 +11,23 @@ import ( const lockDoneHelpDescription = `Usage: - buildkite-agent lock done [key] + buildkite-agent lock done [key] Description: - Completes a do-once lock. This should only be used by the process performing - the work. - Note that this subcommand is only available when an agent has been started - with the ′agent-api′ experiment enabled. +Completes a do-once lock. This should only be used by the process performing +the work. + +Note that this subcommand is only available when an agent has been started +with the ′agent-api′ experiment enabled. Examples: - #!/bin/bash - if [[ $(buildkite-agent lock do llama) == 'do' ]]; then - # your critical section here... - buildkite-agent lock done llama - fi` + #!/bin/bash + if [[ $(buildkite-agent lock do llama) == 'do' ]]; then + # your critical section here... + buildkite-agent lock done llama + fi` type LockDoneConfig struct { // Common config options diff --git a/clicommand/lock_get.go b/clicommand/lock_get.go index 31975eb8d3..76e25e90f9 100644 --- a/clicommand/lock_get.go +++ b/clicommand/lock_get.go @@ -11,23 +11,24 @@ import ( const lockGetHelpDescription = `Usage: - buildkite-agent lock get [key] + buildkite-agent lock get [key] Description: - Retrieves the value of a lock key. Any key not in use returns an empty - string. - Note that this subcommand is only available when an agent has been started - with the ′agent-api′ experiment enabled. +Retrieves the value of a lock key. Any key not in use returns an empty +string. - ′lock get′ is generally only useful for inspecting lock state, as the value - can change concurrently. To acquire or release a lock, use ′lock acquire′ and - ′lock release′. +Note that this subcommand is only available when an agent has been started +with the ′agent-api′ experiment enabled. + +′lock get′ is generally only useful for inspecting lock state, as the value +can change concurrently. To acquire or release a lock, use ′lock acquire′ and +′lock release′. Examples: - $ buildkite-agent lock get llama - Kuzco` + $ buildkite-agent lock get llama + Kuzco` type LockGetConfig struct { // Common config options diff --git a/clicommand/lock_release.go b/clicommand/lock_release.go index 7921c03593..2f25d7d1a4 100644 --- a/clicommand/lock_release.go +++ b/clicommand/lock_release.go @@ -11,23 +11,24 @@ import ( const lockReleaseHelpDescription = `Usage: - buildkite-agent lock release [key] [token] + buildkite-agent lock release [key] [token] Description: - Releases the lock for the given key. This should only be called by the - process that acquired the lock. To help prevent different processes unlocking - each other unintentionally, the output from ′lock acquire′ is required as the - second argument. - Note that this subcommand is only available when an agent has been started - with the ′agent-api′ experiment enabled. +Releases the lock for the given key. This should only be called by the +process that acquired the lock. To help prevent different processes unlocking +each other unintentionally, the output from ′lock acquire′ is required as the +second argument, namely, the ′token′ in the Usage section above. + +Note that this subcommand is only available when an agent has been started +with the ′agent-api′ experiment enabled. Examples: - #!/bin/bash - token=$(buildkite-agent lock acquire llama) - # your critical section here... - buildkite-agent lock release llama "${token}"` + #!/bin/bash + token=$(buildkite-agent lock acquire llama) + # your critical section here... + buildkite-agent lock release llama "${token}"` type LockReleaseConfig struct { // Common config options diff --git a/clicommand/meta_data_exists.go b/clicommand/meta_data_exists.go index 428f16beec..19cd0b5fcb 100644 --- a/clicommand/meta_data_exists.go +++ b/clicommand/meta_data_exists.go @@ -12,16 +12,16 @@ import ( const metaDataExistsHelpDescription = `Usage: - buildkite-agent meta-data exists [options...] + buildkite-agent meta-data exists [options...] Description: - The command exits with a status of 0 if the key has been set, or it will - exit with a status of 100 if the key doesn't exist. +The command exits with a status of 0 if the key has been set, or it will +exit with a status of 100 if the key doesn't exist. Example: - $ buildkite-agent meta-data exists "foo"` + $ buildkite-agent meta-data exists "foo"` type MetaDataExistsConfig struct { Key string `cli:"arg:0" label:"meta-data key" validate:"required"` diff --git a/clicommand/meta_data_get.go b/clicommand/meta_data_get.go index d21c213e5a..bd18337cbd 100644 --- a/clicommand/meta_data_get.go +++ b/clicommand/meta_data_get.go @@ -12,15 +12,15 @@ import ( const metaDataGetHelpDescription = `Usage: - buildkite-agent meta-data get [options...] + buildkite-agent meta-data get [options...] Description: - Get data from a builds key/value store. +Get data from a build's key/value store. Example: - $ buildkite-agent meta-data get "foo"` + $ buildkite-agent meta-data get "foo"` type MetaDataGetConfig struct { Key string `cli:"arg:0" label:"meta-data key" validate:"required"` diff --git a/clicommand/meta_data_keys.go b/clicommand/meta_data_keys.go index 8bbbedffe3..3fa94021ec 100644 --- a/clicommand/meta_data_keys.go +++ b/clicommand/meta_data_keys.go @@ -12,16 +12,16 @@ import ( const metaDataKeysHelpDescription = `Usage: - buildkite-agent meta-data keys [options...] + buildkite-agent meta-data keys [options...] Description: - Lists all meta-data keys that have been previously set, delimited by a newline - and terminated with a trailing newline. +Lists all meta-data keys that have been previously set, delimited by a newline +and terminated with a trailing newline. Example: - $ buildkite-agent meta-data keys` + $ buildkite-agent meta-data keys` type MetaDataKeysConfig struct { Job string `cli:"job"` diff --git a/clicommand/meta_data_set.go b/clicommand/meta_data_set.go index 0c85f5aa58..1928502af9 100644 --- a/clicommand/meta_data_set.go +++ b/clicommand/meta_data_set.go @@ -14,23 +14,23 @@ import ( const metaDataSetHelpDescription = `Usage: - buildkite-agent meta-data set [value] [options...] + buildkite-agent meta-data set [value] [options...] Description: - Set arbitrary data on a build using a basic key/value store. +Set arbitrary data on a build using a basic key/value store. - You can supply the value as an argument to the command, or pipe in a file or - script output. +You can supply the value as an argument to the command, or pipe in a file or +script output. - The value must be a non-empty string, and strings containing only whitespace - characters are not allowed. +The value must be a non-empty string, and strings containing only whitespace +characters are not allowed. Example: - $ buildkite-agent meta-data set "foo" "bar" - $ buildkite-agent meta-data set "foo" < ./tmp/meta-data-value - $ ./script/meta-data-generator | buildkite-agent meta-data set "foo"` + $ buildkite-agent meta-data set "foo" "bar" + $ buildkite-agent meta-data set "foo" < ./tmp/meta-data-value + $ ./script/meta-data-generator | buildkite-agent meta-data set "foo"` type MetaDataSetConfig struct { Key string `cli:"arg:0" label:"meta-data key" validate:"required"` diff --git a/clicommand/oidc_request_token.go b/clicommand/oidc_request_token.go index 790c2ffea1..2c6f66fbaa 100644 --- a/clicommand/oidc_request_token.go +++ b/clicommand/oidc_request_token.go @@ -33,23 +33,24 @@ type OIDCTokenConfig struct { } const ( + backoffSeconds = 2 + maxAttempts = 5 oidcTokenDescription = `Usage: - buildkite-agent oidc request-token [options...] + buildkite-agent oidc request-token [options...] Description: - Requests and prints an OIDC token from Buildkite that claims the Job ID - (amongst other things) and the specified audience. If no audience is - specified, the endpoint's default audience will be claimed. + +Requests and prints an OIDC token from Buildkite that claims the Job ID +(amongst other things) and the specified audience. If no audience is +specified, the endpoint's default audience will be claimed. Example: - $ buildkite-agent oidc request-token --audience sts.amazonaws.com - Requests and prints an OIDC token from Buildkite that claims the Job ID - (amongst other things) and the audience "sts.amazonaws.com". -` - backoffSeconds = 2 - maxAttempts = 5 + $ buildkite-agent oidc request-token --audience sts.amazonaws.com + +Requests and prints an OIDC token from Buildkite that claims the Job ID +(amongst other things) and the audience "sts.amazonaws.com".` ) var OIDCRequestTokenCommand = cli.Command{ diff --git a/clicommand/pipeline_upload.go b/clicommand/pipeline_upload.go index 520d3370ce..bc6e0bc97c 100644 --- a/clicommand/pipeline_upload.go +++ b/clicommand/pipeline_upload.go @@ -30,34 +30,34 @@ import ( const pipelineUploadHelpDescription = `Usage: - buildkite-agent pipeline upload [file] [options...] + buildkite-agent pipeline upload [file] [options...] Description: - Allows you to change the pipeline of a running build by uploading either a - YAML (recommended) or JSON configuration file. If no configuration file is - provided, the command looks for the file in the following locations: - - - buildkite.yml - - buildkite.yaml - - buildkite.json - - .buildkite/pipeline.yml - - .buildkite/pipeline.yaml - - .buildkite/pipeline.json - - buildkite/pipeline.yml - - buildkite/pipeline.yaml - - buildkite/pipeline.json - - You can also pipe build pipelines to the command allowing you to create - scripts that generate dynamic pipelines. The configuration file has a - limit of 500 steps per file. Configuration files with over 500 steps - must be split into multiple files and uploaded in separate steps. +Allows you to change the pipeline of a running build by uploading either a +YAML (recommended) or JSON configuration file. If no configuration file is +provided, the command looks for the file in the following locations: + +- buildkite.yml +- buildkite.yaml +- buildkite.json +- .buildkite/pipeline.yml +- .buildkite/pipeline.yaml +- .buildkite/pipeline.json +- buildkite/pipeline.yml +- buildkite/pipeline.yaml +- buildkite/pipeline.json + +You can also pipe build pipelines to the command allowing you to create +scripts that generate dynamic pipelines. The configuration file has a +limit of 500 steps per file. Configuration files with over 500 steps +must be split into multiple files and uploaded in separate steps. Example: - $ buildkite-agent pipeline upload - $ buildkite-agent pipeline upload my-custom-pipeline.yml - $ ./script/dynamic_step_generator | buildkite-agent pipeline upload` + $ buildkite-agent pipeline upload + $ buildkite-agent pipeline upload my-custom-pipeline.yml + $ ./script/dynamic_step_generator | buildkite-agent pipeline upload` type PipelineUploadConfig struct { FilePath string `cli:"arg:0" label:"upload paths"` diff --git a/clicommand/step_get.go b/clicommand/step_get.go index 330bd00d50..d321bf6048 100644 --- a/clicommand/step_get.go +++ b/clicommand/step_get.go @@ -12,23 +12,23 @@ import ( const stepGetHelpDescription = `Usage: - buildkite-agent step get [options...] + buildkite-agent step get [options...] Description: - Retrieve the value of an attribute in a step. If no attribute is passed, the - entire step will be returned. +Retrieve the value of an attribute in a step. If no attribute is passed, the +entire step will be returned. - In the event a complex object is returned (an object or an array), - you'll need to supply the --format option to tell the agent how it should - output the data (currently only JSON is supported). +In the event a complex object is returned (an object or an array), +you'll need to supply the --format option to tell the agent how it should +output the data (currently only JSON is supported). Example: - $ buildkite-agent step get "label" --step "key" - $ buildkite-agent step get --format json - $ buildkite-agent step get "retry" --format json - $ buildkite-agent step get "state" --step "my-other-step"` + $ buildkite-agent step get "label" --step "key" + $ buildkite-agent step get --format json + $ buildkite-agent step get "retry" --format json + $ buildkite-agent step get "state" --step "my-other-step"` type StepGetConfig struct { Attribute string `cli:"arg:0" label:"step attribute"` diff --git a/clicommand/step_update.go b/clicommand/step_update.go index 10d9ae6e38..f78596e3ab 100644 --- a/clicommand/step_update.go +++ b/clicommand/step_update.go @@ -13,28 +13,28 @@ import ( const stepUpdateHelpDescription = `Usage: - buildkite-agent step update [options...] + buildkite-agent step update [options...] Description: - Update an attribute of a step in the build - - Note that step labels are used in commit status updates, so if you change the - label of a running step, you may end up with an 'orphaned' status update - under the old label, as well as new ones using the updated label. - - To avoid orphaned status updates, in your Pipeline Settings > GitHub: - - * Make sure Update commit statuses is not selected. Note that this prevents - Buildkite from automatically creating and sending statuses for this pipeline, - meaning you will have to handle all commit statuses through the pipeline.yml +Update an attribute of a step in the build + +Note that step labels are used in commit status updates, so if you change the +label of a running step, you may end up with an 'orphaned' status update +under the old label, as well as new ones using the updated label. + +To avoid orphaned status updates, in your Pipeline Settings > GitHub: + +* Make sure Update commit statuses is not selected. Note that this prevents + Buildkite from automatically creating and sending statuses for this pipeline, + meaning you will have to handle all commit statuses through the pipeline.yml Example: - $ buildkite-agent step update "label" "New Label" - $ buildkite-agent step update "label" " (add to end of label)" --append - $ buildkite-agent step update "label" < ./tmp/some-new-label - $ ./script/label-generator | buildkite-agent step update "label"` + $ buildkite-agent step update "label" "New Label" + $ buildkite-agent step update "label" " (add to end of label)" --append + $ buildkite-agent step update "label" < ./tmp/some-new-label + $ ./script/label-generator | buildkite-agent step update "label"` type StepUpdateConfig struct { Attribute string `cli:"arg:0" label:"attribute" validate:"required"` diff --git a/main.go b/main.go index 1de013ac6d..0beaf8fced 100644 --- a/main.go +++ b/main.go @@ -24,7 +24,6 @@ Available commands are: {{range .Commands}}{{.Name}}{{with .ShortName}}, {{.}}{{end}}{{ "\t" }}{{.Usage}} {{end}} Use "{{.Name}} --help" for more information about a command. - ` const subcommandHelpTemplate = `Usage: @@ -33,20 +32,21 @@ const subcommandHelpTemplate = `Usage: Available commands are: - {{range .Commands}}{{.Name}}{{with .ShortName}}, {{.}}{{end}}{{ "\t" }}{{.Usage}} - {{end}}{{if .VisibleFlags}} + {{range .Commands}}{{.Name}}{{with .ShortName}}, {{.}}{{end}}{{ "\t" }}{{.Usage}} + {{end}}{{if .VisibleFlags}} + Options: - {{range .VisibleFlags}}{{.}} - {{end}}{{end}} +{{range .VisibleFlags}} {{.}} +{{end}}{{ end -}} ` const commandHelpTemplate = `{{.Description}} Options: - {{range .VisibleFlags}}{{.}} - {{end}} +{{range .VisibleFlags}} {{.}} +{{ end -}} ` func printVersion(c *cli.Context) { From 014526f3362e7d517384225384bbb8b22a5d057e Mon Sep 17 00:00:00 2001 From: Narthana Epa Date: Wed, 23 Aug 2023 15:12:24 +1000 Subject: [PATCH 2/2] Update link for prime signs As it's in the docs, we should link to the docs rather than a GitHub issue. --- clicommand/prime-signs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clicommand/prime-signs.md b/clicommand/prime-signs.md index f15e723ec8..94732a932c 100644 --- a/clicommand/prime-signs.md +++ b/clicommand/prime-signs.md @@ -5,7 +5,7 @@ CLI helptext, ie: ``` --disconnect-after-job Disconnect the agent after running exactly one job. When used in conjunction with the ′--spawn′ flag, each worker booted will run exactly one job [$BUILDKITE_AGENT_DISCONNECT_AFTER_JOB] ``` -The quotes around --spawn aren't backticks or quotes, but a [prime symbol](https://en.wikipedia.org/wiki/Prime_(symbol)). The reasoning behind this is that urfave/cli, our CLI library, has [special handling](https://github.com/urfave/cli/issues/333) for backticks (`) in helptext, which in our case leads to some (but not all 🙃) of the backticks getting swallowed. +The quotes around --spawn aren't backticks or quotes, but a [prime symbol](https://en.wikipedia.org/wiki/Prime_(symbol)). The reasoning behind this is that urfave/cli, our CLI library, has [special handling](https://cli.urfave.org/v1/examples/flags/#placeholder-values) for backticks (`) in helptext, which in our case leads to some (but not all 🙃) of the backticks getting swallowed. Our workaround for this is to use symbols that look kinda, but not exactly like backticks. Oy. ′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′′