Exercise - Set up your environment

  • 5 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 start to work on your toy company's website workflow, you need to configure your environment. In this unit, you make sure that your Azure and GitHub environments are set up to complete the rest of this module.

To meet these objectives, you'll:

  • Set up a GitHub repository for this module.
  • Clone the project's repository to your computer.
  • Create two workload identities in Microsoft Entra ID.
  • Create two resource groups in Azure.
  • Create secrets and environments in GitHub.

Get the GitHub repository

Here, you make sure that your GitHub repository is set up to complete the rest of this module. You set it up by creating a new repository based on a template repository. The template repository contains the files you need to get started for 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 completed the previous module in the learning path, follow these instructions to create a new repository and ensure that you 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, follow these steps to create a repository from the template:

  1. Select Use this template > Create a new repository.

    Screenshot of the GitHub interface showing the template repo, with the 'Use this template' button highlighted.

  2. Select your GitHub username from the Owner drop-down list.

  3. Enter a repository name for your new project, such as toy-website-end-to-end.

  4. 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 only work with public repositories and with GitHub Enterprise accounts.

  5. Select Create repository.

    Screenshot of the GitHub interface showing the repo creation page.

Important

The final exercise in this module contains important cleanup steps. Be sure to follow the cleanup steps even if you don't complete this module.

Clone the repository

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

  1. Select Code and select the copy icon.

    Screenshot of the GitHub interface showing the new repository, with the repository U R L copy button highlighted.

  2. Open Visual Studio Code.

  3. Open a Visual Studio Code terminal window by selecting Terminal > New Terminal. The window usually opens at the bottom of the screen.

  4. Navigate in the terminal 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-environments folder, run the following command:

    cd toy-website-end-to-end

  5. Type git clone, then paste the URL you copied earlier. The command should look something like this:

    git clone https://github.com/mygithubuser/toy-website-end-to-end.git

  6. Reopen Visual Studio Code in the repository folder by running the following command in the Visual Studio Code terminal:

    code -r toy-website-end-to-end

Sign in to Azure

To work with resource groups in Azure, sign in to your Azure account from the Visual Studio Code terminal. Be sure that you've installed the Azure CLI tools.

  1. In the Terminal menu, select New Terminal. The terminal window usually opens in the lower half of your screen.

    The default shell is typically pwsh, as shown on the right side of the terminal window.

    Screenshot of the Visual Studio Code terminal window, in which pwsh is shown as the shell option.

  2. Select the Launch Profile dropdown list, and then select Azure Cloud Shell (Bash).

    Screenshot of the Visual Studio Code terminal window. The terminal shell dropdown list and the Azure Cloud Shell (Bash) menu item are shown.

    A new shell opens.

Sign in to Azure by using Azure CLI

  1. In the Visual Studio Code terminal, run the following command to sign in to Azure:

    az login

  2. In the browser that opens, sign in to your Azure account.

To work with resource groups in Azure, sign in to your Azure account from the Visual Studio Code terminal. Be sure that you've installed Azure PowerShell.

  1. In the Terminal menu, select New Terminal. The terminal window usually opens in the lower half of your screen.

    The default shell is typically pwsh, as shown on the right side of the terminal window.

    Screenshot of the Visual Studio Code terminal window, in which pwsh is shown as the shell option.

  2. Select the Launch Profile dropdown list, and then select Azure Cloud Shell (PowerShell).

    Screenshot of the Visual Studio Code terminal window. The terminal shell dropdown list and the Azure Cloud Shell (PowerShell) menu item are shown.

    A new shell opens.

Sign in to Azure by using Azure PowerShell

  1. In the Visual Studio Code terminal, run the following command to sign in to Azure:

    Connect-AzAccount

  2. In the browser that opens, sign in to your Azure account.

Create two workload identities

Next, create two workload identities in Microsoft Entra ID: one for your test environment and another for your production environment.

  1. 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-end-to-end'

  2. Create a workload identity for deployments to your test environment. The workload identity needs two federated credentials: one is used when the workflow runs the validate job, because this job isn't associated with a GitHub environment. The second is used when the workflow runs the deploy job, which runs against the Test GitHub environment.

    testApplicationRegistrationDetails=$(az ad app create --display-name 'toy-website-end-to-end-test')
testApplicationRegistrationObjectId=$(echo $testApplicationRegistrationDetails | jq -r '.id')
testApplicationRegistrationAppId=$(echo $testApplicationRegistrationDetails | jq -r '.appId')

az ad app federated-credential create \
   --id $testApplicationRegistrationObjectId \
   --parameters "{\"name\":\"toy-website-end-to-end-test\",\"issuer\":\"https://token.actions.githubusercontent.com\",\"subject\":\"repo:${githubOrganizationName}/${githubRepositoryName}:environment:Test\",\"audiences\":[\"api://AzureADTokenExchange\"]}"

az ad app federated-credential create \
   --id $testApplicationRegistrationObjectId \
   --parameters "{\"name\":\"toy-website-end-to-end-test-branch\",\"issuer\":\"https://token.actions.githubusercontent.com\",\"subject\":\"repo:${githubOrganizationName}/${githubRepositoryName}:ref:refs/heads/main\",\"audiences\":[\"api://AzureADTokenExchange\"]}"

  3. Run the following code, which creates a similar workload identity and federated credentials for the production environment:

    productionApplicationRegistrationDetails=$(az ad app create --display-name 'toy-website-end-to-end-production')
productionApplicationRegistrationObjectId=$(echo $productionApplicationRegistrationDetails | jq -r '.id')
productionApplicationRegistrationAppId=$(echo $productionApplicationRegistrationDetails | jq -r '.appId')

az ad app federated-credential create \
   --id $productionApplicationRegistrationObjectId \
   --parameters "{\"name\":\"toy-website-end-to-end-production\",\"issuer\":\"https://token.actions.githubusercontent.com\",\"subject\":\"repo:${githubOrganizationName}/${githubRepositoryName}:environment:Production\",\"audiences\":[\"api://AzureADTokenExchange\"]}"

az ad app federated-credential create \
   --id $productionApplicationRegistrationObjectId \
   --parameters "{\"name\":\"toy-website-end-to-end-production-branch\",\"issuer\":\"https://token.actions.githubusercontent.com\",\"subject\":\"repo:${githubOrganizationName}/${githubRepositoryName}:ref:refs/heads/main\",\"audiences\":[\"api://AzureADTokenExchange\"]}"

  1. 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-end-to-end'

  2. Run the following code, which creates a workload identity for the test environment and associates it with your GitHub repository:

    $testApplicationRegistration = New-AzADApplication -DisplayName 'toy-website-end-to-end-test'
New-AzADAppFederatedCredential `
   -Name 'toy-website-end-to-end-test' `
   -ApplicationObjectId $testApplicationRegistration.Id `
   -Issuer 'https://token.actions.githubusercontent.com' `
   -Audience 'api://AzureADTokenExchange' `
   -Subject "repo:$($githubOrganizationName)/$($githubRepositoryName):environment:Test"
New-AzADAppFederatedCredential `
   -Name 'toy-website-end-to-end-test-branch' `
   -ApplicationObjectId $testApplicationRegistration.Id `
   -Issuer 'https://token.actions.githubusercontent.com' `
   -Audience 'api://AzureADTokenExchange' `
   -Subject "repo:$($githubOrganizationName)/$($githubRepositoryName):ref:refs/heads/main"

  3. Run the following code, which follows a similar process for the production environment:

    $productionApplicationRegistration = New-AzADApplication -DisplayName 'toy-website-end-to-end-production'
New-AzADAppFederatedCredential `
   -Name 'toy-website-end-to-end-production' `
   -ApplicationObjectId $productionApplicationRegistration.Id `
   -Issuer 'https://token.actions.githubusercontent.com' `
   -Audience 'api://AzureADTokenExchange' `
   -Subject "repo:$($githubOrganizationName)/$($githubRepositoryName):environment:Production"
New-AzADAppFederatedCredential `
   -Name 'toy-website-end-to-end-production-branch' `
   -ApplicationObjectId $productionApplicationRegistration.Id `
   -Issuer 'https://token.actions.githubusercontent.com' `
   -Audience 'api://AzureADTokenExchange' `
   -Subject "repo:$($githubOrganizationName)/$($githubRepositoryName):ref:refs/heads/main"

Create two resource groups in Azure and grant the workload identity access

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

  1. To create the test environment's resource group and grant the workload identity access to it, run the following Azure CLI commands in the Visual Studio Code terminal:

    testResourceGroupResourceId=$(az group create --name ToyWebsiteTest --location westus3 --query id --output tsv)

az ad sp create --id $testApplicationRegistrationObjectId
az role assignment create \
   --assignee $testApplicationRegistrationAppId \
   --role Contributor \
   --scope $testResourceGroupResourceId

  2. Run a similar process to create the production environment's resource group:

    productionResourceGroupResourceId=$(az group create --name ToyWebsiteProduction --location westus3 --query id --output tsv)

az ad sp create --id $productionApplicationRegistrationObjectId
az role assignment create \
   --assignee $productionApplicationRegistrationAppId \
   --role Contributor \
   --scope $productionResourceGroupResourceId

  1. To create the test environment's resource group and grant the workload identity access to it, run the following Azure PowerShell commands in the Visual Studio Code terminal:

    $testResourceGroup = New-AzResourceGroup -Name ToyWebsiteTest -Location westus3

New-AzADServicePrincipal -AppId $($testApplicationRegistration.AppId)
New-AzRoleAssignment `
   -ApplicationId $($testApplicationRegistration.AppId) `
   -RoleDefinitionName Contributor `
   -Scope $($testResourceGroup.ResourceId)

  2. Run a similar process to create the production environment's resource group:

    $productionResourceGroup = New-AzResourceGroup -Name ToyWebsiteProduction -Location westus3

New-AzADServicePrincipal -AppId $($productionApplicationRegistration.AppId)
New-AzRoleAssignment `
   -ApplicationId $($productionApplicationRegistration.AppId) `
   -RoleDefinitionName Contributor `
   -Scope $($productionResourceGroup.ResourceId)

Prepare GitHub secrets

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

echo "AZURE_CLIENT_ID_TEST: $testApplicationRegistrationAppId"
echo "AZURE_CLIENT_ID_PRODUCTION: $productionApplicationRegistrationAppId"
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_TEST: $($testApplicationRegistration.AppId)"
Write-Host "AZURE_CLIENT_ID_PRODUCTION: $($productionApplicationRegistration.AppId)"
Write-Host "AZURE_TENANT_ID: $($azureContext.Tenant.Id)"
Write-Host "AZURE_SUBSCRIPTION_ID: $($azureContext.Subscription.Id)"

Create GitHub secrets

You've created two workload identities, and resource groups that they can deploy to. Next, create secrets in GitHub Actions.

  1. In your browser, navigate to your GitHub repository.

  2. Select Settings > Secrets and variables > Actions.

  3. Select New repository secret.

    Screenshot of the GitHub interface showing the 'Secrets' page, with the 'Create repository secret' button highlighted.

  4. Name the secret AZURE_CLIENT_ID_TEST.

  5. In the Value field, paste the GUID from the first line of the terminal output. Don't include AZURE_CLIENT_ID_TEST, the colon, or any spaces in the value.

  6. Select Add secret.

    Screenshot of the GitHub interface showing the 'New Secret' page, with the name and value completed and the 'Add secret' button highlighted.

  7. Repeat the process to create the secrets for AZURE_CLIENT_ID_PRODUCTION, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID, copying the values from the corresponding fields in the terminal output.

  8. Verify that your list of secrets now shows all four secrets.

    Screenshot of the GitHub interface showing the list of secrets, including both the test and production secrets.

Create environments in GitHub

  1. In your browser, go to Settings > Environments.

  2. Select New environment.

    Screenshot of the GitHub interface that shows the Environments page and the button for creating an environment.

  3. Enter Test as the environment name.

    Screenshot of the GitHub page for a new environment named Test, with the Configure environment button.

  4. Select Configure environment.

  5. Select Environments to return to the environments list.

    Screenshot of the GitHub page for a new environment named Test, with the Environment link.

  6. Repeat the process to create another environment named Production.

Note

In previous modules in this learning path, you added a protection rule to your production environment. In this module, for simplicity, you're skipping the protection rule. However, you can add the protection rule yourself if you'd like.