1. Resources
  2. /
  3. Plugins
  4. /
  5. smooth-checkout-buildkite-plugin

Smooth Checkout

All the things you need during a Buildkite checkout :butter: :kite:

Usage

Repository-less builds

steps:
  - command: echo "Skips checking out Git project in checkout"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          skip_checkout: true

Checking out repo

steps:
  - command: echo "Checks out repo at given ref"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          repos:
            - config:
              - url: git@github.com:<username>/<reponame>.git
                ref: <ref> # (optional)
                clone_flags: <flags> # (optional) flags to use with `git clone` command

If ref is not provided the values of BUILDKITE_BRANCH and BUILDKITE_COMMIT env vars are used.

Allowed values for ref:

  • Branch name
  • Git tag
  • Commit SHA (40 character long hash)

clone_flags can either be a string or an array of strings.

Shallow clone

A shallow clone can easily be done by passing the depth flag in the clone_flags field. For example:

steps:
  - command: echo "shallow clone repo"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          repos:
            - config:
                - url: "git@github.com:hasura/smooth-checkout-buildkite-plugin"
                  clone_flags: "--depth 1"

Checking out multiple repositories

You can checkout multiple repositories by providing multiple config elements:

steps:
  - command: echo "Checks out multiple git repositories"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          repos:
            - config:
              - url: git@github.com:<username>/<repo_1>.git
            - config:
              - url: https://github.com/<username>/<repo_2>.git
                ref: <ref>

Unlike single repo checkouts, when checking out multiple repos, they will each be checked out in subdirectories of $BUILDKITE_BUILD_CHECKOUT_PATH corresponding to the name of the repository (based on its URL). In the above example, the contents of the working directory would be repo_1/ and repo_2/.

You can also explicitly provide the path to an ssh identity file using the ssh_key_path config field:

steps:
  - command: echo "Checks out multiple git repositories"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          repos:
            - config:
              - url: git@github.com:<username>/<repo_1>.git
                ssh_key_path: .ssh/key_1
            - config:
              - url: git@github.com:<username>/<repo_2>.git
                ref: <ref>
                ssh_key_path: .ssh/key_2

If you are using smooth-secrets to configure ssh keys, you can do the following to easily set the ssh_key_path:

steps:
  - command: echo "Checks out multiple git repositories"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          repos:
            - config:
              - url: git@github.com:<username>/<repo>.git
                ssh_key_path: $$SECRETS_DIR/<key>

where <key> is the value of key field in smooth-secrets config with any / characters replaced by -.

Checking out repo from git mirrors

You can attempt to fetch a git repository from git mirrors and fallback to using the original source repo in case of a failure while checking out from mirrors.

steps:
  - command: echo "Checks out repo from mirror (fall back to github in case of failure)"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          repos:
            - config:
              - url: git@mirror.git.interal:/path/to/git/mirror
              - url: git@github.com:<username>/<reponame>.git

Setup & Cleanup

Smooth Checkout also supports setting custom directories for your jobs and deleting the checkout directory after the job completes. BUILDKITE_BUILD_CHECKOUT_PATH is set to the directory specified by the build_checkout_path option. For legacy reasons, the environment variable WORKSPACE is also set to the same value, but its usage is deprecated.

steps:
  - command: echo "Checks out repo to custom directory"
    plugins:
      - hasura/smooth-checkout#v4.4.1:
          build_checkout_path: /tmp/${BUILDKITE_COMMIT}
          delete_checkout: true
          repos:
            - config:
              - url: git@github.com:<username>/<reponame>.git

Use custom directory with interpolation

Additionally, if BUILDKITE_PIPELINE_NO_INTERPOLATION is set to true and custom directory is an interpolation of variables (example: depends on BUILDKITE_JOB_ID, BUILDKITE_STEP_ID etc); use interpolate_checkout_path env to set the directory.

steps:
  - command: echo "Checks out repo to custom directory"
    plugins:
      - hasura/smooth-checkout#v4.2.1:
          interpolate_checkout_path: /tmp/${BUILD_CHECKOUT_PATH}/${BUILD_ID}
          delete_checkout: true
          repos:
            - config:
              - url: git@github.com:<username>/<reponame>.git

Contributing

  • Fork this repo and clone on your machine:
    git clone https://github.com/<your-username>/smooth-checkout-buildkite-plugin
  • Make the required changes
  • Run linter
    docker-compose run --rm lint
  • Run tests (try to add tests for any new features introduced)
    docker-compose run --rm tests
  • Once linter and tests run successfully, open a pull request on this repo

The plugins listed on this webpage are provided for informational purposes only. They have not undergone any formal security review or assessment. While we strive to provide useful resources, we cannot guarantee the safety, reliability, or integrity of these plugins. Users are strongly advised to conduct their own security evaluations before downloading, installing, or using any plugin. By using these plugins, you acknowledge and accept any risks associated with their use. We disclaim any liability for any harm or damages arising from the use of the plugins listed.

Start turning complexity into an advantage

Create an account to get started with a 30-day free trial. No credit card required.

Buildkite Pipelines

Platform

  1. Pipelines
  2. Pipeline templates
  3. Public pipelines
  4. Test Engine
  5. Package Registries
  6. Mobile Delivery Cloud
  7. Pricing

Hosting options

  1. Self-hosted agents
  2. Mac hosted agents
  3. Linux hosted agents

Resources

  1. Docs
  2. Blog
  3. Changelog
  4. Webinars
  5. Plugins
  6. Case studies
  7. Events
  8. Migration Services
  9. Comparisons

Company

  1. About
  2. Careers
  3. Press
  4. Brand assets
  5. Contact

Solutions

  1. Replace Jenkins
  2. Workflows for AI/ML
  3. Testing at scale
  4. Monorepo mojo
  5. Bazel orchestration

Legal

  1. Terms of Service
  2. Acceptable Use Policy
  3. Privacy Policy
  4. Subprocessors
  5. Service Level Agreement

Support

  1. System status
  2. Forum
© Buildkite Pty Ltd 2025