Not all BUILDKITE_* environment variables are documented

[therealbnut]

BUILDKITE_DISABLE_GIT_SUBMODULES buildkite/agent#168 isn’t listed on:

• https://buildkite.com/docs/builds/environment-variables, or
• https://buildkite.com/docs/agent/configuration

[therealbnut]

After further investigation it doesn't seem to be an option anymore, but there are others missing.

[therealbnut]

I ran this on https://github.com/buildkite/agent/ and https://github.com/buildkite/docs/

cd agent
grep -ohr -e 'BUILDKITE_[a-zA-Z0-9_\-]*[a-zA-Z0-9]*' . | sort | uniq > /tmp/agent.txt
cd ../docs
grep -ohr -e 'BUILDKITE_[a-zA-Z0-9_\-]*[a-zA-Z0-9]' . | sort | uniq > /tmp/docs.txt

Then ran git diff /tmp/agent.txt /tmp/docs.txt | grep '^[+-]' > /tmp/agent-docs.diff and got:

-BUILDKITE_AGENT_EXPERIMENT
-BUILDKITE_AGENT_META_DATA_GCP
+BUILDKITE_AGENT_META_DATA_LOCAL
-BUILDKITE_AGENT_PID
-BUILDKITE_BIN_PATH
+BUILDKITE_BUILD_CREATOR
+BUILDKITE_BUILD_CREATOR_EMAIL
+BUILDKITE_BUILD_URL
-BUILDKITE_COMMAND_EVAL
-BUILDKITE_COMMAND_EXIT_STATUS
-BUILDKITE_DOWNLOAD_EXIT_STATUS
-BUILDKITE_DOWNLOAD_TMP_FILE
+BUILDKITE_DOCKER
+BUILDKITE_DOCKER_COMPOSE_CONTAINER
+BUILDKITE_DOCKER_COMPOSE_FILE
+BUILDKITE_DOCKER_FILE
-BUILDKITE_GIT_SUBMODULES
-BUILDKITE_GS_ACL
-BUILDKITE_GS_APPLICATION_CREDENTIALS
-BUILDKITE_INSTALL_ARCH
-BUILDKITE_LAST_HOOK_EXIT_STATUS
+BUILDKITE_MESSAGE
+BUILDKITE_META_DATA
+BUILDKITE_PARALLEL
+BUILDKITE_PARALLEL_JOB_COUNT
+BUILDKITE_PIPELINE_DEFAULT_BRANCH
-BUILDKITE_PLUGIN
-BUILDKITE_PLUGINS
-BUILDKITE_PLUGINS_PATH
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_AND_WITH_A_NUMBER
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_ARRAY_KEY_0
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_ARRAY_KEY_1
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_ARRAY_KEY_2
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_CONFIG_KEY
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_CONTAINER
-BUILDKITE_PLUGIN_DOCKER_COMPOSE_SOME_OTHER_SETTING
+BUILDKITE_PRIORITY
-BUILDKITE_REFSPEC
-BUILDKITE_S3_ACCESS_KEY
+BUILDKITE_REPO_SSH_HOST
-BUILDKITE_S3_SECRET_KEY
-BUILDKITE_SSH_FINGERPRINT_VERIFICATION
-BUILDKITE_USER
-BUILDKITE_USER_GROUP
+BUILDKITE_TIMEOUT

The + lines probably indicate something that's in the docs, but not in the agent, this may just mean that it's in a different repo.

[sj26]

Excellent point, we're definitely missing a bunch, especially the ones provided by the agent process, or used to configure the agent. It was pointed out in buildkite chat that the $BUILDKITE_S3_* variables used to specify the artifact destination aren't documented except on the artifact command line docs page, too.

The ones not in the agent repo are provided by buildkite.com for use by build scripts, hooks and plugins.

[lox]

Specifically BUILDKITE_COMMAND_EXIT_STATUS would be good to add, perhaps in the hooks documentation as that is where it's mostly relevant.

[jerrymarino]

💯 - these docs would be useful. I'm currently looking to get the status of Preparing working directory in a post-checkout and also the status of command in a post-command hook.

[harrietgrace]

Hey @jerrymarino! 👋🏻It took us a while, but we've finally done a big update to the env vars doc 😄There was also a recent agent update that cleaned up a bunch of the vars it was displaying too, so everything should be covered now.

[nh2]

• https://buildkite.com/docs/builds/environment-variables, or

• https://buildkite.com/docs/agent/configuration

It looks like only the first of these two was done, the other one was forgotten. I filed #501 for it.