bug: Buildkite plugin argument environment variable naming unexpected

[austinguo550]

I recently noticed that the naming scheme described in the Writing Plugins documentation is not always accurate. Namely, the naming convention for plugin arguments exported as environment variables appears to change based on the repository name length. Because we use full length URLs to reference our plugins, I expect the naming convention to follow what the documentation says here:

However, this is not always the case. Below I have pasted an example to illustrate what I mean.

In example number 1, I have a plugin named repository-one. The plugin in the pipeline.yaml appears as follows:

[2022-08-23T01:36:43Z]   plugins:
--
  | [2022-08-23T01:36:43Z]   - ssh://[email protected]/<org>/repository-one.git#<commit sha>:
  | [2022-08-23T01:36:43Z]       command: <command>

The environment variable for the argument "command" is exported as "BUILDKITE_PLUGIN_REPOSITORY_ONE_GIT_COMMAND" which follows the naming scheme I would expect.

In example number 2, I have a plugin named repository-two-buildkite-plugin. The plugin in the pipeline.yaml appears as follows:

[2022-08-26T22:48:37Z]   plugins:
--
  | [2022-08-26T22:48:37Z]   - ssh://[email protected]/<org>/repository-two-buildkite-plugin.git#<commit sha>:
  | [2022-08-26T22:48:37Z]       command: <command>

However, in this example the environment variable for the argument "command" is exported as "BUILDKITE_PLUGIN_REPOSITORY_TWO_COMMAND". This is very different from what the docs say above.

Is there some complication in the underlying logic that determines what the plugin arguments will be named when they are exported as environment variables? My hypothesis is that the naming convention may have changed somehow because the second example plugin repo name was too long. I would love to get some clarity on this, as this behavior was very unexpected and hard to debug, and I want to make sure this won't change arbitrarily on us down the road and break our pipelines.

NOTE: the repositories names are substituted with placeholders above, but the names follow the regex:

• repository-one -> [a-z]{9}-[a-z]{7}
• repository-two-buildkite-plugin -> [a-z]{9}-[a-z]{4}-buildkite-plugin

[pda]

Thanks for the very clear write-up @austinguo550!

I did some digging, and found this: https://github.com/buildkite/agent/blob/6fec074dce224d039821b3d650eb3f4062e69b24/agent/plugin/plugin.go#L139-L144

So, -buildkite-plugin and -buildkite-plugin.git suffixes are trimmed, whereas the .git suffix is not trimmed if the repo name doesn't end with buildkite-plugin. I think our recommendation would be to name plugin repos with -buildkite-plugin suffix.

In fact reading https://buildkite.com/docs/plugins/writing#step-1-create-a-new-git-repository it says this:

Every Buildkite plugin is a Git repository, ending in -buildkite-plugin. This suffix is required: Buildkite automatically adds -buildkite-plugin to the plugin name specified in the pipeline.yml.

So perhaps it's mandatory for everything to work as expected? (Maybe the agent should provide better warnings/diagnostics when a plugin name doesn't match that suffix?)

[austinguo550]

Interesting, I see. Thank you! That's very reassuring to know the naming is still deterministic and doesn't arbitrarily truncate. My bad for missing that piece of documentation on creating the git repository.

Better warnings and diagnostics would probably make this more explicitly clear! Although from my standpoint I've figured out what I'd like to know and am ok with closing the ticket