TL/DR: To assist QA in managing multiple projects on multiple environments, we’ve developed a command line tool to find and run builds using CircleCI and GitHub API. It uses AWS SSM parameter for configuration. It is available on GitHub under the name what-build.

Continuous Deploy Will Do It For You

At the start of almost any project you can get away for some time with running deploy from your machine. But if your team has more than one person and if your project and team are growing, pretty soon deploy from your machine is not an option. Usually what that means is that deploy script or tool stays the same but it is running on a CI/CD tool of choice. In our case this was a CircleCI build that was triggered by a GitHub push. It is easy to assume that most of the projects have some variant of a similar setup, at least at some point in their lives.

Around the same time our quality assurance process required deploying a version of upcoming changes to one of their environments for a closer look. We decided to use the same CircleCI deploy build but give it some additional data on where to deploy with build parameters. And since we had a number of projects that were interacting with each other, it was also important to know which version of which project was deployed on each environment. We needed a tool.

What Build Do We Have On A QA Environment?

This is where having somewhat regular Hack Days was really advantageous. And there is no better project for learning a new programming language than a command line API-caller.
Additional goal that I’ve set for myself was to separate as much as possible configuration from code. So that adding new projects, new environments or new deploy options would not require changing code of the tool itself.

The resulting what-build can be found on GitHub. The main function of the tool is to find or to rerun with a different set of build parameters a build in CircleCI. The setup requires a user to have an IAM credentials in team AWS account. To be able to run what-build one needs two things:

  • The tool reads its configuration from AWS SSM Parameter Store as json. It defines what builds a user can search and execute. You can revoke access to a config at any time and the config itself can be different for different users.
  • Assuming you have your Github team setup, every user is asked to log in on the first what-build run. The user credentials are not stored, but used to generate a token, that a user themselves can revoke at any time. Having different access to team resources on the GitHub level also determines what a user can do.

How It Works

Say, you have a project in a cozy GitHub + CircleCI setup. A configuration part for it may look like this:

  "name": "myProject",
  "circleci_url": "",
  "github_url": "",

And then suppose you have a QA environment. CircleCI deploys your project there if environment has DEPLOY_ENV=QA. Then in the build section you might have something like this:

  "name": "qa",
  "search_build_parameters": {
    "DEPLOY_ENV": "QA"
  "run_build_parameters": {
    "DEPLOY_ENV": "QA",
    "SOME_OTHER_VAR": "true"

Now what-build can look for the latest project build with parameters specified in the config:

$ what-build find -p myProject -b qa

Project myProject:
CircleCI Build qa status success at 12:59 10.11.2019 by <iam.username>
- Branch: my-branch
- Commit: Commit message header
- Revision: <revision_sha>

Using the same API, what-build can trigger a build with parameters, provided the branch was pushed to GitHub and CircleCI has a build for it. It looks for a branch among open pull requests, since it was our QA process. But it can use any remote branch. This process is interactive and lets you select a PR or a branch as well as build options:

$ what-build run -p myProject -b qa
✔ The name of an open Pull Request
✔ default
CircleCI Build qa status not_running by <iam.username>
- Branch: branch-name-of-the-pr
- Commit: Commit message of the HEAD
- Revision: <revision_sha>

Currently the tool supports two ways to authenticate on CircleCI: a token or a name of an SSM parameter with a token. It also supports AWS CodeBuild, but only for finding a build, not triggering at the moment. You are welcome to try it out and/or provide some feedback. I’m open to questions and comments.

The team can now swiftly tell which version of any project is deployed on any QA environment. Quality assurance team can deploy any pull request to any environment. As our team grows further a setup may change, and we will update or replace this tool. That is a part of growing. And that is good.