• 5 min read

Azure Automation: Integrating Runbook Source Control using Visual Studio Online

Introduction Azure Automation can be great for managing Azure resources and 3rd party systems, but what if you want to manage Azure Automation’s resources (runbooks, modules, assets, etc), themselves?…


Azure Automation can be great for managing Azure resources and 3rd party systems, but what if you want to manage Azure Automation’s resources (runbooks, modules, assets, etc), themselves?  Of course, the Azure Automation portal and the Azure Automation PowerShell cmdlets give you the capabilities to do basic management tasks, but what if you want to use a source control system to store your runbooks, modules, and assets, to allow for tracking changes, auditing, restoring from an earlier version, and moving versions between dev, staging, and production branches to allow for change control?

It turns out, with a little runbook magic, we can set up Azure Automation to support continuous integration of our Automation resources into itself based on a source control system. This blog post will specifically describe how you can use Azure Automation to repeatedly query a Visual Studio Online (VSO) git repository, and automatically publish any runbooks (ps1 files) from this source control repository into an Automation account. While this blog will only talk about runbooks, you could of course similarly use Azure Automation to continuously integrate modules and assets stored in source control into Azure Automation as well.


The Sync-VsoGitRunbook Runbook

The runbook that accompanies this blog, Sync-VsoGitRunbook, will perform all the tasks for this scenario.  This runbook is now available.  Grab your copy now:

Download runbook

The illustration below highlights the full process for continuously integrating runbooks stored in source control into an Azure Automation account. The great part about the integration is you can manage your runbooks simply by managing your VSO git repository as you normally would:

  • As you make updates to your runbooks, you commit and push those updates to your VSO git repository.
  • If you want to revert an update, you simply revert the commit.
  • If you want to promote updates in your staging branch to production, you simply merge staging into production.

The Sync-VsoGitRunbook runbook takes parameters to tell it what VSO git repository to sync from, and what Azure Automation account to sync to. You could sync to the Automation account running this runbook, or to another one. Internally, the runbook grabs the contents of the specified VSO git repository, and then imports and publishes the runbooks recursively (child runbooks before parent runbooks) into the specified Azure Automation account.

The runbook can be started manually to do an on-demand sync of your Azure Automation account with the VSO git repository, or you can use a schedule asset to automate the sync on a schedule. By setting up multiple executions of this runbook on a schedule, each execution against a different Git branch and Azure Automation account, you can achieve QA-to-Production change control. For example, you could have one scheduled runbook which has parameter values for the git staging branch and your staging automation account, and one scheduled runbook which has parameter values for the git production branch and your production automation account. This would cause your staging Automation account to sync with the staging git branch, and your production automation account to sync with the production git branch. Merging from the git staging branch to the git production branch will move those updated runbooks into your production Automation account automatically!


Runbook scenario flow-chart


Setting up Visual Studio Online

To start, you will need to have a Visual Studio Online account, and have a project and repository configured.  You can start here.

To configure your git project and repository, follow this blog.


Creating a sample project

At this point, you are ready to create a Visual Studio project for your Automation runbooks.  In my example, I am using a simple Empty Project.


Blank project


Project structure for your runbooks

As for the structure of the project, you should have a hierarchy of folders containing your runbooks, with parent runbooks in highest level directories, their children in sub directories, their children’s children in subdirectories to the subdirectories, etc.  The runbook will recursively walk the directory tree and publish the runbooks in the lowest subdirectories (most-child runbooks) first and move its way up, so that child runbooks are always imported before the runbooks that call them (parent runbooks).  This is needed because the Azure Automation service requires all child runbooks to be published first.

To illustrate:

Parent to child directory structure


with similar structure in Visual Studio online project view:


Directory structure in VSO


Setting up VSO an alternate authentication credentials

For the Sync-VsoGitRunbook runbook to work, it uses VSO alternate authentication credentials as configured from “My Profile,” available in the Visual Studio Online dashboard (top right).

In the User Profile dialog, select Credentials to define an alternative authentication credential.  This username and password will be used as input to the Sync-VsoGitRunbook runbook.


Alternate Credential User Profile dialog



Starting the Sync-VsoGitRunbook runbook

  1. If you haven’t already, set up your Azure Automation account to be able to manage your Azure subscription using the Connect-Azure runbook.  See this blog post (if you have IIS) or this blog post (if you don’t have IIS) for details.
  2. Download the Sync-VsoGitRunbook runbook from Script Center:  Download runbook
  3. Import and publish the Sync-VsoGitRunbook runbook
  4. Create the following Azure Automation asset
    • Credential – this asset contains the alternate authentication credential username and password
    • Connection – create an Azure connection type with subscription ID of where the published to Automation Account resides
  5. Add a daily schedule of the Sync-VsoGitRunbook runbook with the following parameters
    • VSOCredentialName – Name of the credential asset containing the VSO Alternate Authentication Credential name and password configured from VSO Profile dialog.
    • VSOAccount – Name of the account name for VSO Online (Ex. https://accountname.visualstudio.com)
    • VSOProject – Name of the VSO project that contains the repository
    • VSORepository – Name of the repository that contains the runbook project
    • VSORunbookFolderPath – Project path to the root where the runbooks are located.  Using the example below, use /Project1/Project1

              Runbook folder path

    • VSOBranch – Optional, defaults to “master”. The branch name used to query runbook details
    • AutomationAccount – Name of the Automation Account where the runbooks should be synced to
    • AzureConnection – Name of the Azure connection setting that was created in the Automation service.  This connection setting contains the subscription id and the name of the certificate setting that holds the management certificate.



The Sync-VsoGitRunbook runbook illustrates how you could take advantage of source control management and continuous integration for your runbooks.  The scenario demonstrated in this blog post could also be done with any other online source control system, such as GitHub.  There’s even already an Azure Automation runbook on ScriptCenter to get you started downloading the contents of a GitHub repository to Azure Automation. Using that runbook, you could build a solution similar to the one demonstrated in this blog post, but targeting GitHub as your source control system! As you can see, Azure Automation is a truly powerful automation and integration service.

Not an Azure Automation user yet? Sign up for the preview and then check out the Getting Started guide.