Creating Custom Reports using the Upsun CLI
Does X exist?
Someone recently asked meDoes a tool / report exist for the last deployment date for production sites - this will help find out if our sites are… out of date?There isn’t a single pane in the console that list all the sites in your organization with the last date of a push to the production branch. But, one of the amazing things about Upsun is that our product is API-first. Whether you are performing an action in the Console, or using the CLI, they’re both just calling the API for you. The Upsun API itself is extensive and gives you everything you need in order to build just about anything you can imagine. And a report showing this information is entirely achievable! The Upsun CLI is really just a convenient wrapper for you to access the API from the command line, so for this example, I’ll use the CLI, but you can accomplish the exact same task using the API directly (or the recent Upsun PHP SDK). The other nice thing about the CLI is that it has a built-in
multi command that allows you to perform the same
command against multiple projects at once. To use it, you hand it a comma separated list of project IDs and then the
command you want to perform on each one.
First we need IDs
For this example, I want the date of the last deployment (orpush activity event)
for my projects that start with the title “Template | ”. Since I know multi needs a list of project IDs, I’ll need to
get those first. To grab a list of projects by their title, I can use the
project:list command with the --title
parameter to filter on the project title.
multi so I’ll pipe the output from this command to
tr (translate) to transform newlines to commas.
Note: I’m going to limit the number of projects to 5 using the --count parameter just to make this easier to show.
Finding the date of the last deploy
Now that we have the list of project IDs, we can pass this information to themulti command. But before we do that, we
need to know how to get the date of the last deployment of a project. Every time you push a change to an active
environment, Upsun will deploy that change, rebuilding the containers if necessary. With that in mind, we need to find
when the last push occurred to project’s default environment. For purposes of this example, we’re going to assume that
all of our projects are using the same production branch name of main.
One of the things the API exposes about your project is every
activity that occurs to the
project. In the CLI, we can use the
activity:list command to retrieve all
activities in a project.
push activities so let’s add the --type parameter to limit the returned activities to only
push events.
Note: The actual activity type name for a push activity event is
environment.push. However,
the CLI allows us to
omit the first part of an activity’s name for
convenience.push event AND we only want the date, so let’s add in a --limit of 1 (the default is to
sort by activity date - Created - descending) and select only the Created column. We also don’t need the table
format or header, so let’s use --format=plain and --no-header to remove those.
push activity to hand to the multi command!
Combing the commands to generate our report
Let’s combine this command with themulti command and use the command to retrieve our project IDs from earlier to get
a complete report on the last time each project had a push event!
Go forth and report
I hope this has given you some ideas on the flexibility and power the Upsun API possesses and how you can utilize this to create your own reports catered to your unique business needs, even when what you need doesn’t already exist.Bonus items
Date Format
It’s possible you’ll need that activity date in a different format. Don’t worry: we’ve got you covered. Theactivity:list command accepts a --date-fmt
parameter allowing you to alter the date format
using a PHP date format string.
Limit to successful pushes
In the example above, the person asking for the report wanted any push events to the project. It’s possible though in your situation that you only want those where the push (and build) was successful. To filter to those events where the result of a push was successful, we can add the--result parameter with a value of success to our activity:list
command.
Simplified command option if you want everything
In the example I used, I needed to limit the number of IDs returned from theproject:list command to just 5 to make
the example easier to read. If you don’t need to limit the number of projects to a smaller amount than what matches,
you can simplify the project:list command by using the
--pipe parameter, which returns a simple list
of project IDs, disabling any pagination in the returned results. In our example, adding the --pipe parameter would
result in a much more succinct command:
My projects don’t all use the same production branch name
While standardization is great and should be the ideal, reality isn’t always so cooperative. Perhaps you inherited a project, or some projects were set up before you standardized on the production name. In order to accomplish the example above, we need some ability to retrieve the production branch name in order to pass that to theupsun multi command.
We could perform a preliminary upsun multi command that retrieves each project’s default_branch using the
upsun project:info command. However, this adds significant complexity to what we’re trying to achieve. Our CLI
attempts to be very accommodating and make things easier on our users. That includes the ability to use a period (.)
to represent a project’s default environment! This allows us to update our previous command to work with all our
projects even if they do not use the same default_branch name!