Azure Automation: Sync Runbooks from Visual Studio Team Services

Windows PowerShell, Azure Infrastructure


This is sort of an update or branch off of a blog post by Gary Keong titled: Azure Automation: Integrating Runbook Source Control using Visual Studio Online (July 2014) and includes some of my learnings.

Use Case

We are going to sync some runbooks for the purposes of subscription management. This could include things like setting up alerts, applying permissions, and applying policies to the subscription. I’m going to assume you have a Visual Studio Team Services Account (create one if not).

In this example, I will use two Azure Automation Accounts.

  • The first one will hold the “Sync Runbook.” It simply syncs my Visual Studio Team Services (VSTS) Git repository to my second Automation Account. We’ll call this the Sync Automation Account.
  • The second one will hold the runbooks that manage the subscription. We’ll call this the Manager Automation Account.

The two Automation Accounts could be in separate subscriptions. For example, the first one may be in an IT-owned “management” subscription, while the other may be in the subscription it is managing.

The runbook to perform this sync provided in the original article (by Gary Keong) could be considered outdated. I found an updated version on Joe Brockhaus’ GitHub called AzureAutomationVsoGitSync. I needed to make some tweaks because Joe’s module uses a username and password for the Manager Automation Account. My company enforces multi-factor authentication for all users, so that’s not an option. Instead, we’re going to use a Service Principal.

Prepare Automation Accounts

As explained above, we’re using two different automation accounts. If you don’t have them created, create them now. The Manager Automation Account is going to be populated (with runbooks) for us and should be created with the “AzureRunAs” account. Once created we do need to add some assets.

First, we need a Service Principal. We’re going to create one just for the purpose of assigning permissions to the Manager Automation Account. You can use this script (link) to create it (requires at least Windows 10). The script:

  • Creates a self-signed certificate
  • Uses it to create a Key Credential
  • Creates AD Service Principal and Application using the Key Credential
  • Assigns Contributor role for the Automation Account to the Service Principal
  • Defines several Azure Automation (variable) Assets and a Certificate asset that will be used to connect to Azure later. Note, the variable names and the certificate name is hard-coded in the script to use the same names as the sync module expects.

You need to define the parameters in the beginning of the file and then run each region by itself (sorry for the poor design).

Automation Account: Set up runbook

Next, we will setup the Sync Automation Account. If you don’t have this created, create it now. We do not need an AzureRunAs account for this one.

  1. Upload the module
    1. Download the modified AzureAutomationVsoGitSync module from my GitHub and add it to the Automation Account using the Modules blade. Azure Automation expects the .zip format.
  2. Upload the runbook
    1. Download the PowerShell file from my GitHub and save it as a .ps1 file. (direct link)
    2. You can also download via PowerShell: Invoke-WebRequest -uri “″ -OutFile $env:TEMP\Sync-AzureRmRunbooks.ps1
    3. Click on the Runbooks blade and click “Add a runbook”
    4. Upload the Sync-AzureRmRunbooks.
    5. Click on the runbook, select Edit, and then Publish.


Prepare VSTS

Let’s prepare to use the Sync runbook. First, we need to set up alternate authentication credentials in Visual Studio Team Services (VSTS). Tip: click on the images below to enlarge them.

    1. Login to your VSTS account. Click on your name (or profile icon) on the top right and click on Security.
    2. Select “Alternate authentication credentials” from the menu on the left.
    3. Ensure the checkbox is checked and enter a password in the password boxes
    4. Keep the username and password handy (note them down), as we’ll be using these later.
    5. Now we are going to create a Service Hook.  Go back to your project and click on settings
    6. Click on Service Hooks and click “Create subscription”
    7. Scroll down to Web Hooks and press Next.
    8. For this post, we are going to trigger on code push to the master branch.
    9. Click finish.
    10. While we’re here, copy down the values in the following settings
Parameter Value


Setup Syncing

Automation Account: Set up webhook

We need a way to tell the Sync Automation Account, specifically the Sync-AzureRmRunbooks runbook to start. We’ll use a Webhook to do that.

    1. Create Credential Asset
      1. Now that we’ve set up alternate authentication, we need to add that to our runbook so it can authenticate with VSTS.
      2. Navigate to the Sync Automation Account and click on the Credentials blade.
      3. Click “Add a credential” and fill-in the form with your VSTS alternate authentication.
    2. Create a webhook
      1. Now, ensure the Sync-AzureRmRunbooks is selected.
      2. Click the Webhooks tile and click “Add Webhook”
      3. Select “Create new webhook” and give it a name such as “SyncRunbookOnCodePush”
      4. Keep the other defaults and copy the URL. WARNING: You can’t find this URL again, so copy it safely somewhere now, we’re going to use it in a minute.
      5. Now click “Configure parameters and run settings”
      6. Fill in the values using the table in the previous section.

VSTS: Create Service Hook

  1. Create a Service Hook by browsing to your VSTS Project’s Settings page.
  2. Click Service Hooks. Scroll down and select Web Hooks. Click Next.
  3. We are going to use a “Code pushed” trigger.
  4. On the next screen, paste in the URL from step #4 in the previous section. Leave everything else as default and press Test.
  5. Hopefully the test succeeds, press Finish. If the test failed, re-check your webhook or re-create it.

Final Validation

The final validation is ensuring the process works end to end. To perform this test, add a runbook to your VSTS repository, commit it and push the changes.

Since the trigger is on “Code pushed,” you should be able to browse to your Sync Automation Account and see a job in the queue. The out put will look similar to this:

When it completes (without error), you’ll now see this runbook in your Manager Automation Account. Note, runbooks that were deleted from your repository don’t get deleted but we could extend this scenario to do that also.

So that you can check your setup, here’s how each Automation Account should look:

Description Sync Automation Account Manager Automation Account
Purpose Syncs runbooks from Git repo Holds runbooks to run against subscription
Runbooks Sync-AzureRmRunbooks None, until synced.
Modules AzureAutomationVsoGitSync None, just default.
Credentials VSTS Alt. Authentication None.
Variables AutomationAppId
Connections None AzureRunAsConnection
Certificates AutomationCertificate AzureRunAsCertificate
1 comment… add one

Leave a Reply