Ability to customize checkout behavior

[GMNGeoffrey]

Is your feature request related to a problem? Please describe. I want to have a pipeline that triggers on a pull request, but checks out the main branch and runs some scripts from there to decide whether it's ok to run builds on that PR. Currently I'm using a skip-checkout plugin and then wget to manually fetch all the files. It's a bit gross. I could do a manual git fetch instead of wget here, but that's pretty verbose and copy-pasta from the Buildkite checkout logs. There's also the smooth-checkout plugin, which unfortunately also has some custom behavior for checkout directory. I think there are a fair number of plugins and feature requests around more control of the checkout process. I could of course create my own hook, but I find agent hooks a really unpalatable mechanism for this sort of configurability because they're totally opaque to the pipeline. They make sense for things like locking down agent security, but not really for customizing individual step behavior.

Another use case is checking out the merge commit for a PR instead of the head commit, which there are a few plugins implementing in various ways, all of which involve somewhat complex configuration over multiple steps:

• https://github.com/seek-oss/github-merged-pr-buildkite-plugin
• https://github.com/juliaci/pull-request-merge-commit-buildkite-plugin

Describe the solution you'd like The commit buildkite checks out after fetching should be something settable with an environment variable. Then I could set BUILDKITE_REFSPEC=refs/heads/main and BUILDKITE_CHECKOUT_COMMIT=FETCH_HEAD using something like the metahook plugin. I think it's good to leave BUILDKITE_COMMIT immutable and default BUILDKITE_CHECKOUT_COMMIT to BUILDKITE_COMMIT.

Describe alternatives you've considered An option in Buildkite to always checkout FETCH_HEAD

Ideally, this would be something that Buildkite would offer more direct support for, but I think the method using environment variables and leveraging this existing plugin would be easier in the short term.

I could also write my own plugin or contribute to one of the existing checkout customization plugins, but based on my survey of them it seems like they frequently end up being especially tailored to an individual use case and also reinventing a lot of Buildkite's checkout logic. It's pretty heavy-weight to have to create an entire repository to check out a different commit.

Some other plugins customizing checkout behavior:

• https://github.com/arromer/github-fetch-buildkite-plugin
• https://github.com/uber-workflow/run-without-clone-buildkite-plugin
• https://github.com/first-aml/git-clone-buildkite-plugin
• https://github.com/peakon/git-shallow-clone-buildkite-plugin
• https://github.com/pragmaplatform/sparse-checkout-buildkite-plugin

[alexsapran]

I am facing the same issue and am interested if there are any planned improvements on this or if we should just have to write our own plugin.