The Octo.exe – your utility knife for automation
If you’ve started using Octopus Deploy and want to fully maximize it’s potential via automation but you don’t know where to start, you need to begin investigating the Octo.exe. The Octo.exe is a neat little utility that allows you, through the command-line (and by extension, PowerShell) to interact with your Octopus Server without using the web interface. There’s a number of functions that the Octo.exe serves but from a high-level, it’s all about interacting with your projects. Whether it’s deleting an old release to creating a new release and deploying it or promoting a current release, most of what you can do through the browser can be done by extension with the Octo.exe. So what exactly can we do with the Octo.exe?
The Octopus Documentation on the Octo.exe is pretty good place to start on what it can do. Another way to look at what can be done is to download the Octo.exe itself from the downloads page and simply execute it from the command line with no parameters:
As you can see to the right, there’s a nice list of things we can do. When would you ever use this though? The most common applications I’ve used the Octo.exe so far have been:
1. Deployment automation (i.e. continuous deployments) – For teams that want to deploy immediately after the TFS build is finished whether by check-in or a queued build, we use the Octo.exe and a PowerShell script to create a release (create-release command with the deployTo parameter). By using the create-release command, Octopus Deploy will use the latest version of the NuGet package to deploy a new release to the desired environment. You can deploy to multiple environments if you wish by supplying multiple –deployTo arguments, but by far most teams just deploy to their development environment. I’ll be posting a step-by-step guide to setting up continuous deployments.
2. Recurring scheduled deployments – Using the task scheduler in Windows, I can call a PowerShell script on an interval to test the Octopus Deploy Server for deployments. This is a type of synthetic transaction that allows us to run deployments without any user intervention to see if our Octopus Server and/or environments/networks are running well. Any deployment fails and we receive an email. It’s a nice little bit of automation and very simple to implement.
3. Reporting on deployments – There’s a utility within the Octo.exe that allows you to export deployment data using the dump-deployments parameter and feed the results into a report. There’s step-by-step instructions on the Octopus documentation site on how to generate reports. We were using this function for a few months but we now have our own reporting mechanism that leverages other assets that Octopus Deploy publishes that I’ll briefly cover further along.
4. Deleting a range of releases – Sometimes people feel the need to delete a prior release or several.. manually one-by-one. Users may not know that they don’t need to because retention policies can automatically scrub old releases defined within the Octopus Server. Additionally, some may not know that in order to rollback to a previous deployment, you need to keep that release history. Either way, people delete releases one-by-one. Yikes. You can use the Octo.exe to delete a range of deployments should you need to delete a lot of releases. If you run the command “Octo.exe help delete-releases” you can see the parameters ‘minversion’ and ‘maxversion’. Simply use the correct parameters and delete a slew of old releases in one command rather than one at a time through the Octopus Web Portal.
Most of the use cases here are common for our needs. Continuous deployments are by far the #1 reason for using the Octo.exe. Your needs may also vary from mine but just know that the Octo.exe is available should you need it. At this point you may wonder, how does the Octo.exe work exactly?
Remember when I said at the beginning of this deep dive that the Octo.exe is a good place to start? There are two other utilities at your disposal; the Octopus Client Assembly DLL and the Octopus REST API. The REST API (Representational State Transfer; Application Programming Interface) is the core of what makes Octopus Deploy so customizable and adept in many situations. I’m not going to dive into the REST API (too much) here, I’ll cover it in another deep dive but I wanted to give you a glimpse as to why I think Octopus Deploy trumps any other release management solution available today.
The REST API is really the heart of Octopus Deploy. Everything goes through it – the Web Portal, the Octo.exe and the Octopus Client Assembly. As simple as it may appear, it’s what allows anyone to customize to their hearts content on top of it. The Octo.exe is an extension of Octopus Deploy via the REST API and you don’t have to deal with any of the details. Everything uses the REST API. With the core architecture being completely REST API driven, all utilities and functionality share the same expected results. Testing is much simpler and results are more consistent throughout. It’s one of the key reasons the Octopus developers are able to put forth new features and fixes rapidly.
The Octo.exe is the first tool you could use to leverage the REST API. Don’t neglect this utility. It comes in very handy, especially if you’re looking to do basic automation of tasks that you’d normally do in the Web Portal such as deploying your project or deleting a release. If you want something the the Octo.exe doesn’t provide, you can use the REST API via the Octopus client assembly or PowerShell. That’s how we do our reporting now – with a custom C# WebForms application. We connect to the Octopus Server via the REST API with the client assemblies and work with the underlying data from RavenDB. From this, we’ve built reports with really interesting statistics that Octopus Deploy doesn’t offer. We also provision new projects for teams by automating the creation of project groups, projects, teams, permissions and environments all using PowerShell to interact with the REST API. Could we have done this with any other product? I highly doubt it.
With the client assembly and PowerShell, we were able to scale and automate Octopus for our enterprise sized needs. We have over 150 project groups with 250 projects, hundreds of developers all over the world and approaching several thousand deployments per month all on just one Octopus Deploy Server. It may seem like a tiny-cute-n-little product but if you know how to maximize it and leverage automation with it, it’s impact is powerful. Don’t be afraid to automate with Octopus – it was built for it from day zero. But if you want to just dip your toes in the automation “pool”, try out the Octo.exe – it’s a great utility knife for automation with Octopus Deploy.
That’ll do it for this deep dive on the Octo.exe. I will be covering both the REST API and the Octopus Client Assembly in future deep dives.