or, How as a support engineer I wrote our most-used orb to date (and how you can too)
Experience in open source
If you’re a new developer, I’m here to encourage you to consider writing an orb. Orbs are a great way to add some open source experience to your resume while demonstrating most of the skills software engineering roles look for.
- Open source development experience
- Experience with continuous integration and continuous deployment
- Git and Bash experience
It’s really easy to hit all of these major points with a simple orb, even one that just posts messages to a Slack channel. This is, in fact, what I did build, and what I will discuss in this blog post.
Who am I?
Hey, I’m Kyle, a Support Engineer here at CircleCI. If you’ve contacted support before, we’ve probably already met. I also try to provide support outside the email system, writing support center articles, creating videos, and now Orbs! I suppose we can add blog posts too.
I have the advantage of talking with many of our users and observing the creative solutions you all have come up with to simplify your development and I try to take these observations and present to you the best solutions possible or sometimes changes we should make to our team.
Some background on orbs
A few months ago we heard from the product team that soon we would be releasing “Orbs”, a package manager for CircleCI config files. As an example, you could use orbs to easily configure an AWS S3 upload without worrying about installing the AWS CLI or creating an AWS config file. With an orb like this, you don’t need to worry about the AWS side at all, and you shouldn’t have to! Your focus is your project; you expect an S3 upload to just work without needing to maintain it. With orbs, that’s exactly how it will be for just about everything.
To upload to S3 for instance, it is this simple:
Import the orb
orbs:
aws-s3: circleci/aws-s3@volatile
Then, whenever you want, in any job, run the sync command in a step
- aws-s3/sync:
from: bucket
to: 's3://my-s3-bucket-name/prefix'
overwrite: true
That’s it! All orbs are open source so you can see how this was made and read the docs on how to use it on its page on our new Orb Registry: https://circleci.com/developer/orbs/orb/circleci/aws-s3
Using orbs, it’s incredibly easy for anyone to quickly implement tons of integrations, tools, utilities, features, or anything else you can think of, and share them.
This may or may not also make me super happy as a support engineer! There’s nothing better than having a standardized solution to present everyone, and one that’s easy to maintain as a single package.
The first step: solving a simple problem
Before orbs were launched to the public, the product team was tasked with working on an initial set of orbs for the release, and they invited the other teams to be a part of the process and contribute orbs as well. Since I’ll be one of the people answering your questions about orbs, I took the opportunity to create an orb that I thought would be useful to a lot of people.
Since I talk directly with users, I knew that you all wanted more control over Slack notifications: when they are sent, what is sent, who is alerted, maybe even the color of the message. So I decided to create an orb to do just that. The process of creating an orb was really straightforward, and this showed me how easy it can be to make an open source contribution that a lot of people will use and improve. In fact, the Slack orb I wrote is now our most used orb to date.
“I had no idea when I started how far the project would grow and become shaped by the community.”
Watching the community grow
Since I wrote the Slack orb, I’ve gotten a lot of pull requests from users like you who want to use and improve the Slack orb for their own projects. What started as essentially a wrapper for a CURL request has grown into a robust, by-the-people for-the-people interface between CI and Slack, with advanced features such as the ability to receive rich notifications when a deployment is awaiting your approval. I had no idea when I started how far the project would grow and become shaped by the community.
A look at the Slack orb
Let’s take a look at the Slack orb, what it does, and how it does it. You can take the principles here and apply them to just about any tool or CLI out there.
If you want to follow along with the source or just check out the Slack orb yourself, you can visit the Orb Registry.
What it does
While the orb has now evolved a bit since its creation, the original Slack orb started with only 2 commands, “notify” and “status”:
Let’s take a look at the notify command.
jobs:
alertme:
docker:
- image: circleci/node
steps:
- slack/notify:
message: "This is a custom message notification"
#Enter your own message
mentions: "USERID1,USERID2"
#Enter the Slack IDs of any users who should be alerted to this message.
color: "#42e2f4"
#Assign custom colors for each notification
webhook: "webhook"
#Enter a specific webhook here or the default will use $SLACK_WEBHOOK
notify allows you to easily craft a custom Slack notification in any job. This allows you extra freedom in sending your notifications in several ways.
First, you can set several parameters such as the message text, any users to @ mention, and even the color of the box the message is presented in.
You also have the inherent benefit of the notifications running conditionally based on the job, meaning you can just add the notify command to your deployment job and choose to alert a team member if you choose.
What’s most exciting is that the flexibility of orbs means you will likely come up with creative uses for this orb that I had not even considered.
If you want to know more about the Slack orb, take a look at its page on the Orb Registry. Want to contribute and improve the Slack Orb? It’s open source! Send us a PR and we’ll take a look.
How I built my orb (and how you definitely can too)
This project started on my personal Github and was later moved to the official CircleCI organization when it was ready for launch. If you are looking for any inspiration or proof that no one is perfect (or even close to it) you can check out the git commit history to see all the trial and error involved with getting this working. To be honest I feel like at least 100 of those commits were struggling with quotes, double quotes, and escaped characters.
You can see what it has become today through updates and pull requests at its new home on the CircleCI-Public page: https://github.com/CircleCI-Public/slack-orb
Now it’s your turn: why author an orb?
Why choose an orb for your open source project? Because it’s easy to get started and offers a lot of experience with important development skills, and since it’s open source, CircleCI will build it for free!
Join the Open Source community: We recently started getting the first “Issues” reported on the Slack orb repo, which is an awesome feeling just to know that developers are using your code.
Since creating the Slack orb we have received several pull requests, responded to several issues by releasing patches or new features, and constructed a more robust development pipeline using Workflows and the CLI for automatic deployment
Real world skills: Creating an orb or improving an existing one is an incredibly easy way to get involved in the open source community while gaining the real-world experience employers look for.
Orbs inherently make use of Git version control, CI/CD and often shell scripting, along with any other CLI or tools you may interact with along the process.
Writing something that posts messages to a Slack channel using CURL contains nearly every experience you need to have to become a professional developer. If you are looking to break into the field I could not imagine a better way to get started.
In my next post, I share my best tips and things to consider when creating an orb. Ready for more? Explore orbs.
