Exercise - Set up your environment

4 minutes

Important

You need your own Azure subscription to run this exercise, and you might incur charges. If you don't already have an Azure subscription, create a free account before you begin.

Before you set up your toy company's pull-request workflows, you need to configure your environment.

In this unit, you make sure that your Azure and GitHub environments are set up so that you can complete the rest of this module successfully.

To meet these objectives, you'll:

Set up a GitHub repository for this module.
Clone the repository to your computer.
Create a workload identity in Microsoft Entra ID.
Create a secret in GitHub.

Get the GitHub repository

In this section, you set up your GitHub repository to complete the rest of this module by creating a new repository based on a template repository. The template repository contains the files you need to get started on this module.

The modules in this learning path are part of a progression. For learning purposes, each module has an associated GitHub template repository.

Tip

Even if you've already completed the previous module in the learning path, follow these instructions to create a new repository and give it a new name.

Start from the template repository

Run a template that sets up your GitHub repository.

Run the template

On the GitHub site, create a repository from the template by doing the following steps:

Select Use this template > Create a new repository.
Note the name of your GitHub username or organization. In the example, the GitHub user name is mygithubuser. You'll need this name soon.
Enter a name for your new project, such as toy-website-auto-review.
Select the Public option.

When you create your own repositories, you might want to make them private. In this module, you'll work with some features of GitHub that work only with public repositories and GitHub Enterprise accounts.
Select Create repository.

Clone the repository

You now have a copy of the template repository in your own account. Clone this repository locally so you can start to work in it.

Select Code, and then select the copy icon.
Open Visual Studio Code.
Open a Visual Studio Code terminal window by selecting Terminal > New Terminal. The window usually opens at the bottom of the screen.
In the terminal, go to the directory where you want to clone the GitHub repository on your local computer. For example, to clone the repository to the toy-website-auto-review folder, run the following command:
```
cd toy-website-auto-review
```
Type git clone and then paste the URL you copied earlier, which looks something like this:
```
git clone https://github.com/mygithubuser/toy-website-auto-review.git
```
Reopen Visual Studio Code in the repository folder by running the following command in the Visual Studio Code terminal:
```
code -r toy-website-auto-review
```

Now that you've cloned the repository locally to your computer, you'll sign in to your Azure environment. You'll use your Azure account to create a workload identity for your GitHub Actions workflows to use.

In the Visual Studio Code terminal, run the following command to sign in to Azure:
```
az login
```
In the browser that opens, sign in to your Azure account.

In the Visual Studio Code terminal, sign in to Azure by running the following command:
```
Connect-AzAccount
```
In the browser that opens, sign in to your Azure account.

Create a workload identity

Later in this Microsoft Learn module, your pull request workflow will create resource groups and resources in your subscription. To deploy resources, you need to create a workload identity and grant it the Contributor role on your subscription.

Warning

The workload identity that you create here has a high level of access to your Azure subscription. To avoid any accidental issues, use a nonproduction subscription. Don't execute these steps in an environment that holds any of your production workloads.

In your own pull request validation workflows, we recommend that you use a dedicated Azure subscription.

To create the workload identities, the Azure CLI commands use jq to parse data from JSON output. If you don't have jq installed, you can use Bash in Azure Cloud Shell to create the workload identity, resource group, and role assignment, and prepare the GitHub secrets.

Run the following code to define variables for your GitHub username and your repository name. Ensure that you replace mygithubuser with your GitHub username, which you noted earlier in this exercise. Also ensure that you specify the correct GitHub repository name.
```
githubOrganizationName='mygithubuser'
githubRepositoryName='toy-website-auto-review'
```

Create a workload identity for your deployments workflow.

applicationRegistrationDetails=$(az ad app create --display-name 'toy-website-auto-review')
applicationRegistrationObjectId=$(echo $applicationRegistrationDetails | jq -r '.id')
applicationRegistrationAppId=$(echo $applicationRegistrationDetails | jq -r '.appId')

az ad app federated-credential create \
   --id $applicationRegistrationObjectId \
   --parameters "{\"name\":\"toy-website-auto-review\",\"issuer\":\"https://token.actions.githubusercontent.com\",\"subject\":\"repo:${githubOrganizationName}/${githubRepositoryName}:pull_request\",\"audiences\":[\"api://AzureADTokenExchange\"]}"

Run the following code to define variables for your GitHub username and your repository name. Ensure that you replace mygithubuser with your GitHub username, which you noted earlier in this exercise. Also ensure that you specify the correct GitHub repository name.
```
$githubOrganizationName = 'mygithubuser'
$githubRepositoryName = 'toy-website-auto-review'
```

Create a workload identity for your deployments workflow.

$applicationRegistration = New-AzADApplication -DisplayName 'toy-website-auto-review'
New-AzADAppFederatedCredential `
   -Name 'toy-website-auto-review' `
   -ApplicationObjectId $applicationRegistration.Id `
   -Issuer 'https://token.actions.githubusercontent.com' `
   -Audience 'api://AzureADTokenExchange' `
   -Subject "repo:$($githubOrganizationName)/$($githubRepositoryName):pull_request"

Grant the workload identity access to your subscription

Next, create a resource group for your website. This process also grants the workload identity the Contributor role on the resource group, which allows your workflow to deploy to the resource group.

Run the following Azure CLI commands in the Visual Studio Code terminal:

az ad sp create --id $applicationRegistrationObjectId
az role assignment create \
   --assignee $applicationRegistrationAppId \
   --role Contributor

Run the following Azure PowerShell commands in the Visual Studio Code terminal:

New-AzADServicePrincipal -AppId $applicationRegistration.AppId
New-AzRoleAssignment `
   -ApplicationId $applicationRegistration.AppId `
   -RoleDefinitionName Contributor

Prepare GitHub secrets

Run the following code to show you the values you need to create as GitHub secrets:

echo "AZURE_CLIENT_ID: $applicationRegistrationAppId"
echo "AZURE_TENANT_ID: $(az account show --query tenantId --output tsv)"
echo "AZURE_SUBSCRIPTION_ID: $(az account show --query id --output tsv)"

$azureContext = Get-AzContext
Write-Host "AZURE_CLIENT_ID: $($applicationRegistration.AppId)"
Write-Host "AZURE_TENANT_ID: $($azureContext.Tenant.Id)"
Write-Host "AZURE_SUBSCRIPTION_ID: $($azureContext.Subscription.Id)"

Make a note of your application ID value for the AZURE_CLIENT_ID. You can use that value when you clean up resources when you're finished with this module.

Create GitHub secrets

You've created a workload identity, and granted it permission to deploy to the subscription. Next, create secrets in GitHub Actions.

In your browser, navigate to your GitHub repository.
Select Settings > Secrets and variables > Actions.
Select New repository secret.
Name the secret AZURE_CLIENT_ID.
In the Value field, paste the GUID from the first line of the terminal output. Don't include AZURE_CLIENT_ID, the colon, or any spaces in the value.
Select Add secret.
Repeat the process to create the secrets for AZURE_TENANT_ID and AZURE_SUBSCRIPTION_ID, copying the values from the corresponding fields in the terminal output.
Verify that your list of secrets now shows all three secrets.