Relay and Open Source

Blog post cover

Relay and the open source community

Relay is deliberately built to be easy to extend. The more steps there are in the world the better it is for everyone who wants to write a workflow. It’s sort of like fax machines or MySpace: you’ll want to use the same technology that the people you’re communicating with use. OK, maybe the fax machine isn’t not a great analogy… the point is, nourishing a healthy open-source ecosystem and community around Relay is super important to its success.

In this post I’ll talk about the different aspects of Relay’s open source DNA: the ecosystem model, the codebase itself, and upstream projects.

The Relay Ecosystem

First and foremost, Relay is about workflows. Relay workflows are a well-defined YAML dialect that’s readily sharable. The first batch of workflows we’ve been writing to exercise the system and demonstrate its capabilities are on the Workflows section of the website with READMEs for example usage and a one-click button to add them to your account. The code for all of them is collected in the puppetlabs/relay-workflows repo. We’d love to see pull requests with bug fixes or improvements, new workflows you’ve written to solve problems with Relay, or requests for features. Be sure to check out the reference documentation on the workflow format and our templating language for more information on writing your own workflows.

Relay workflows make use of containers to both respond to incoming events and to run as steps to accomplish the task you’re trying to automate. Step and Trigger container definitions that interact with a particular tool or service can be bundled up into what we call an Integration. The Integrations library on the website has a browsable, taxonomized list of the currently supported integrations.

We expect the current list will cover a lot of common Relay use cases, but there’s no way it’s going to cover all of them. If you run into the situation where there’s an integration with a service you use, but not a specific Step or Trigger that does what you want, we’d love to hear about it! Many of the features marked “Coming soon” on the integration pages just need some prioritization and tweaking to get out the door, and your vote counts to help get them on the list. Plus, all of the integrations are aggregated together under the relay-integrations Github organization, and by now it should go without saying that we welcome any PRs or issues on them.

To make a new integration, or if you want to go further than tweaking the existing containers, there’s a long-form Integrating with Relay guide that breaks down the different container types, the Python SDK, and best practices for integrating with the internal Relay service APIs.

The Relay Codebase

Speaking of documentation, the entire Relay documentation site is available on Github. If you run across anything in the docs that doesn’t seem right, from typos to examples that don’t work, we’d welcome corrections in the form of PRs or issues. Sending pull requests into the docs can be a great way to get involved with a project. Docs are generally on a quicker release cycle than the codebase and everybody benefits from having improved documentation.

If you’re a Go developer, whether aspirational (like me!) or expert, the Relay CLI tool could present a fun opportunity to dig into a relatively constrained codebase and improve the Relay development experience. I’ve written at length about our philosophy of CLI design, something I personally am pretty passionate about, and it’s been really gratifying to see those design principles come to life in the Relay CLI. There are a few issues tagged with CLI to get started, and of course we welcome your ideas too.

Going deeper into the architecture, the Kubernetes execution backend for the service is published at puppetlabs/relay-core. There are some intriguing possibilities for this codebase, like adding a local executor that could use minikube to run workflows locally. The metadata service would also be useful to have as a self-hosted version, because it would allow better validation and testing of step definitions while you’re developing workflows.

Of potential interest to front-end folks, the Puppet Design System is an open source collection of React components that the Relay web app (among other Puppet products) uses to provide gorgeous, modern look-and-feel.


Relay makes heavy use of upstream open source technology. We try to be good citizens of these projects by contributing bug fixes and enhancements back upstream. This helps everybody because we don’t end up maintaining forks or carrying our own patches, the code gets more eyes on it, and the rest of the community can make use of the features too.

The projects we’re most heavily involved in are Tekton pipelines, which we’ve blogged about extensively and Ambassador, who posted a detailed technical blog post describing how Relay uses Knative and Ambassador together to run your Trigger containers.


To wrap things up, I’d like to acknowledge that open source is tough to get right. Communities are valuable, fragile things, which need lots of love and attention to flourish. We’re deeply committed to investing in community for Relay, but acknowledge up front that we won’t always get it right. We pledge to listen and improve based on your feedback. You can email the team at or jump on to chat in #relay. Please keep the lines of communication open and let’s build some awesome automation together!