{"id":18142233,"url":"https://github.com/gusto/buildkite-builder","last_synced_at":"2026-01-12T07:07:51.182Z","repository":{"id":37932551,"uuid":"312392061","full_name":"Gusto/buildkite-builder","owner":"Gusto","description":"A Ruby DSL for programmatically creating Buildkite pipelines.","archived":false,"fork":false,"pushed_at":"2025-03-26T19:16:48.000Z","size":297,"stargazers_count":48,"open_issues_count":6,"forks_count":8,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-03T01:08:15.380Z","etag":null,"topics":["buildkite","docker-image","ruby","rubygem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gusto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-12T20:47:40.000Z","updated_at":"2025-03-26T19:16:52.000Z","dependencies_parsed_at":"2023-01-30T02:46:30.890Z","dependency_job_id":"3168b86a-4951-4863-8a0e-da20dab4e3f2","html_url":"https://github.com/Gusto/buildkite-builder","commit_stats":{"total_commits":102,"total_committers":9,"mean_commits":"11.333333333333334","dds":0.4509803921568627,"last_synced_commit":"cec74cb5e37370f283ca48837e7ec5704c21defd"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gusto%2Fbuildkite-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gusto%2Fbuildkite-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gusto%2Fbuildkite-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gusto%2Fbuildkite-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gusto","download_url":"https://codeload.github.com/Gusto/buildkite-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142068,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildkite","docker-image","ruby","rubygem"],"created_at":"2024-11-01T18:06:15.739Z","updated_at":"2026-01-12T07:07:51.169Z","avatar_url":"https://github.com/Gusto.png","language":"Ruby","readme":"# Buildkite Builder [![Build status](https://badge.buildkite.com/a26bf804e9a93fb118d29824d5695a601a248ceec51591be23.svg?branch=main)](https://buildkite.com/gusto-open-source/buildkite-builder/builds?branch=main)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"350\" height=\"260\" alt=\"Buildkite-Builder Logo\" src=\"https://github.com/user-attachments/assets/216608a5-7b1a-4766-b60b-0dc24f50e492\"\u003e\n\u003c/p\u003e\n\n## Introduction\n\nBuildkite Builder (BKB) is a Buildkite pipeline builder written in Ruby. It allows you to build your pipeline with a Ruby DSL for dynamically generated pipeline steps.\n\n## Gem Installation (optional)\n\nThere are 2 components to this toolkit. The `buildkite-builder` RubyGem and the `buildkite-builder` Docker image. You technically only need the image to use Buildkite Builder, but installing the gem in your repo helps you preview your pipeline during development.\n\nTo install the gem, add this line to your application's Gemfile:\n\n```ruby\ngem 'buildkite-builder'\n```\n\nThe gem provides a command line tool that lets you perform various operations on your pipelines:\n\n```shell\n  buildkite-builder help\n```\n\n## Pipeline Installation\n\nAs with every Buildkite pipeline, you'll need to define the initial pipeline step. You can do this directly in the Pipeline Settings or with a `.buildkite/pipeline.yml` file in your repository. You'll need to define a single step to kick off Buildkite Builder:\n\n```yaml\nsteps:\n  - label: \":toolbox:\"\n    key: \"buildkite-builder\"\n    retry:\n      automatic:\n        - exit_status: -1 # Agent was lost\n          limit: 2\n        - exit_status: 255 # Forced agent shutdown\n          limit: 2\n    plugins:\n      - docker#v5.12.0:\n          image: \"gusto/buildkite-builder:4.13.0\"\n          mount-buildkite-agent: true\n          propagate-environment: true\n```\n\nSome things to note:\n\n- The `label` can be whatever you like.\n- You'll want to update the `docker` plugin version from time to time.\n- You can update the `buildkite-builder` version by bumping the Docker image tag.\n\n## Usage\n\n💡 We have a [Showcase pipeline](https://buildkite.com/gusto-open-source/showcase/builds/latest?branch=main) (defined in [`.buildkite/pipelines/showcase/pipeline.rb`](https://github.com/Gusto/buildkite-builder/blob/main/.buildkite/pipelines/showcase/pipeline.rb)) that, well, showcases some of the features and possibilities with Buildkite Builder. Sometimes the best way to learning something is seeing how it's used.\n\nAt its core, BKB is really just a YAML builder. This tool allows you to scale your needs when it comes to building a Buildkite pipeline. Your pipeline can be as straight forward as you'd like, or as complex as you need. Since you have Ruby at your disposal, you can do some cool things like:\n\n- Perform pre-build code/diff analysis to determine whether or not to to add a step to the pipeline.\n- Reorder pipeline steps dynamically.\n- Augment your pipeline steps with BKB processors.\n\n### Pipeline Files\n\nYour repo can contain as many pipeline definitions as you'd like. By convention, pipeline file structure are as such:\n\n```console\n.buildkite/\n  pipelines/\n    \u003cyour-pipeline1-slug\u003e/\n      pipeline.rb\n    \u003cyour-pipeline2-slug\u003e/\n      pipeline.rb\n```\n\nFor an example, refer to the [dummy pipeline in the fixtures directory](https://github.com/Gusto/buildkite-builder/blob/main/spec/fixtures/basic/.buildkite/pipelines/dummy/pipeline.rb).\n\n### Defining Steps\n\nBuildkite Builder was designed to be as intuitive as possible by making DSL match Buildkite's attributes and [step types](https://buildkite.com/docs/pipelines/defining-steps#step-types). Here's a basic pipeline:\n\n```ruby\nBuildkite::Builder.pipeline do\n  command do\n    label \"Rspec\", emoji: :rspec\n    command \"bundle exec rspec\"\n  end\n\n  wait\n\n  trigger do\n    trigger \"deploy-pipeline\"\n  end\nend\n```\n\nWhich generates:\n\n```yaml\nsteps:\n  - label: \":rspec: RSpec\"\n    command: \"bundle exec rspec\"\n  - wait\n  - trigger: deploy-pipeline\n```\n\nIf the step type or attribute exists in Buildkite docs, then it should exist in the DSL. **The only exception is the `if` attribute**. Since `if` is a ruby keyword, we've mapped it to `condition`.\n\n### Step Templates\n\nIf your pipeline has a lot of steps, you should consider using Step Templates. Templates allow you to break out your build steps into reusable template files.\n\n```console\n.buildkite/\n  pipelines/\n    foobar-widget/\n      pipeline.rb\n      templates/\n        rspec.rb\n        rubocop.rb\n```\n\nA template is basically a step that was extracted from the pipeline:\n\n`.buildkite/pipelines/foobar-widget/templates/rspec.rb`\n\n```ruby\nBuildkite::Builder.template do\n  label \"Rspec\", emoji: :rspec\n  commmand \"bundle exec rspec\"\nend\n```\n\nYou can then include the template into the the pipeline once or as many time as you need. The template name will be the name of the file (without the extension).\n\n`.buildkite/pipelines/foobar-widget/pipeline.rb`\n\n```ruby\nBuildkite::Builder.pipeline do\n  command(:rspec)\n\n  # Reuse and agument templates on the fly.\n  command(:rspec) do\n    label \"Run RSpec again!\"\n  end\nend\n```\n\n### Extensions\n\nExtensions provide additional flexibility to run code and encapsulate reusable patterns in your pipelines. Think of extensions as Ruby modules that let you define custom DSL, step templates, and shared logic that can be used across multiple pipelines.\n\nExtensions are useful when you want to standardize how certain steps are defined, or when you want to use or share complex logic (like deployment, notifications, or test orchestration).\n\n`.buildkite/pipelines/foobar-widget/extensions/deploy_extension.rb`\n\n```ruby\nclass DeployExtension \u003c Buildkite::Builder::Extension\n  dsl do\n    def deploy_step(\u0026block)\n      command(:deploy, \u0026block)\n    end\n  end\nend\n```\n\n`.buildkite/pipelines/foobar-widget/pipeline.rb`\n\n```ruby\nBuildkite::Builder.pipeline do\n  deploy_step do\n    label \"Deploy to production (EU)\"\n    command \"bundle exec deploy --env production --region eu\"\n  end\nend\n```\n\n#### Extension Templates\n\nExtensions can also provide multiple templates for different scenarios:\n\n```ruby\nclass TestExtension \u003c Buildkite::Builder::Extension\n  template :default do\n    command \"bundle exec rspec\"\n  end\n\n  template :rubocop do\n    command \"bundle exec rubocop\"\n  end\nend\n```\n\nAnd used like this in the pipeline file:\n\n```ruby\ncommand(TestExtension) # Uses the default template\n\ncommand(TestExtension.template(:rubocop)) do\n  label \"Custom Rubocop label\"\nend\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at \u003chttps://github.com/gusto/buildkite-builder\u003e. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/gusto/buildkite-builder/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the `Buildkite::Builder` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/gusto/buildkite-builder/blob/main/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgusto%2Fbuildkite-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgusto%2Fbuildkite-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgusto%2Fbuildkite-builder/lists"}