Introduction

By placing scripts under source control, changes can to scripts can be tracked, and the introduction of a change that causes an issue can be resolved by reverting to an earlier version of a script. This guide provides instructions on how to prepare the Azure environment permissions to support source control and how to configure a repository to handle Azure Runbooks.

Instructions

Preparing the Azure Environment

This only needs to be done once in the environment prior to the first repository is being created. Subsequent repositories can be added by following the instructions in the section named “Configuring a Repository” below.

Navigate to https://dev.azure.com/speakeasy-aphasia/_settings/organizationPolicy
and set “Third-party application access via OAuth” to “On” (the default is off)

Navigate to Azure home: https://portal.azure.com/#home. Click on “Speakeasy”

Select Access Control (IAM) from LHS menu. Click “Add role assignment” button in RHS pane and add “Contributor”. The end result should look like the following:

The above permission is probably a little over the top, as a job function role could possibly be used, but it works!

Configuring a repository

Navigate to Azure home: https://portal.azure.com/#home. Click on “SpeakeasyAutomation…Source Control…Add”

Specify a name (e.g. “SpeakeasyRunbooks”), and source control type (e.g. Azure DevOps(Git)”). Click “Authenticate” and follow any instructions that appear. Save changes.

See the following screenshot which shows the configuration of the SpeakeasyRunbooks repository:

Note that “Autosync” and “Publish Runbook” have been set to “On” so that commits automatically push changes to the runbook area and mark them as published (i.e. not “In Edit”).

Accessing the Repository from a Desktop Computer

Download and install a copy of the git software to a desktop computer from: https://git-scm.com/downloads

Navigate to https://dev.azure.com/speakeasy-aphasia/_git/SpeakeasyAzureRunbooks to see which DevOps projects are available. Pick the SpeakeasyRunbooks project, then click on
“Repos” in the left-hand side pane. Click the “Clone” button.

Click the “generate git credentials” button to obtain a password and save this temporarily in Notepad.

Select HTTPS and copy the command that appears. From a command prompt in a suitable root
directory. I created a root folder in my personal OneDrive called : OneDrive\Personal\SpeakeasyGitWorkingFolders – don’t put the folder under Teams as this is overkil given files will be stored in the cloud in Azure DevOps), type “git clone” followed by the
HTTPS location, e.g.:

git clone https://speakeasy-aphasia@dev.azure.com/speakeasy-aphasia/SpeakeasyAzureRunbooks/_git/SpeakeasyAzureRunbooks

When prompted, enter the password that was saved in Notepad. If this was not saved, click the “generate git credentials” button again to get a new password.

A SpeakeasyAzureRunbooks folder should then appear under C:\Users\cashy\OneDrive\Personal\SpeakeasyGitWorkingFolders. This is the working folder for the user who wishes to make changes to the scripts.

Making changes to scripts

Make changes to scripts, using “git commit” and “git push” to commit and push the changes from the working folder back to the Azure DevOps repository.Alternatively, use the git gui command to do the same.

Note: we could deploy a more extensive pipeline mechanism, but this is overkill for runbooks.

New files can also be added to the working folder – it is easier to add these to the repository via the “git gui” command.

Any changes made to runbook scripts should then shortly be visible if the runbooks are viewed via SpeakeasyAutomation…Runbooks in Azure

It is important that users do not try not to edit runbook scripts directly via SpeakeasyAutomation, unless absolutely have to, e.g. to test some Azure specific behaviour as opposed to testing via desktop. If this is done, remember to copy the changed script and paste it into the appropriate script file in your working folder, then commit and push the changes