I began interning at effx roughly three weeks ago (we’re building a best of breed service catalog 😎). Recently, I finished integrating a GitHub Action that allows users to sync service configurations to their effx accounts. I didn’t even know GitHub Actions were a thing, prior to building this integration.
So, as you could imagine, the development process included a lot of learning and tinkering. This post is meant to describe why GitHub Actions are so powerful and showcase the first GitHub Action I've helped build.
What’s all the hype about?
The tagline on for GitHub Actions on their home page reads, “Automate your workflow from idea to production”. In non-buzzwordy language, GitHub Actions let you run code on GitHub. This is a game changer. Better yet, code can be triggered by tons of different events, so it’s very flexible. Check out this repo for a huge list of example use cases.
GitHub Actions have two components: workflows and actions. Workflows are triggered by events and are made up of actions. Actions are Docker containers that run in a workflow.
Use case at effx
We want our users to be empowered with the option to configure their effx accounts programmatically.
Since we’re building a service catalog, configurations can include adding new services and teams, as well as updating service ownership. Programmatic configuration is especially important for companies with lots of services and teams. For example,
- manually inputting teams and their respective members would be incredibly time consuming, not to mention tedious, for large organizations
- programmatic configurations can be checked into version control
By default, the GitHub Action we built allows users to sync
effx.yaml configuration files within a GitHub repo with their effx account, whenever a commit is made to this repo's
master branch. As mentioned, there are many events that can trigger a GitHub Action. Pushing to
master felt like a nice default, but this can always be changed by a user. 🙂
I helped develop
effx-sync-action. Below is a screenshot of what this single-action workflow looks like. Note that directory is set to
githubis an environment variable that's provided for free). We opted to use
/github/workspace by default because it allows us to scan an entire repo for effx configuration files.
GitHub Actions lets you have an
action.yml file that provides metadata. This file is a place for you to specify inputs, outputs, and an entry point for the action. Our
action.yml file defines directory as an input and passes it to our Dockerfile, which pulls the effx CLI.
The effx CLI tool processes the entire repo, if directory is set to
/github/workspace, takes care of parsing
effx.yml files, and updates the user's effx account configurations accordingly.
Add an Action to a Repo
- Create a top-level directory called
.githubinside the repo you want to add an Action to.
.github, create a directory called
workflows. This is where you'll put all of the files for the Actions associated with this repo.
workflows, create a
.ymlfile. The name of file doesn't matter. If you can't think of a silly name,
hello_world.ymlmight be a safe bet.
- Navigate to GitHub Marketplace and browse the Actions. On an Action's detail page, you'll see a button titled, "Use latest version". You'll be prompted with some YAML. Copy and paste it into the
.ymlfile you created in the previous step.
Congrats, you just added a GitHub Action to your repo! 🥳
If you want to add
effx-sync-action to your repo, head over to the Action's repo by clicking here. Happy syncing! 🎉