Skip to content

Commit 42ba367

Browse files
heiskrheiskr
authored
Update course format for accessibility (#46)
* Update course format for accessibility * outline step files * More automatic fixes * Manual fixes * manual fixes * run prettier * manual fixes * manual fixes * manual fixes
1 parent cee60a6 commit 42ba367

26 files changed

+917
-923
lines changed

‎.github/script/STEP renamed to ‎.github/steps/-step.txt

File renamed without changes.

‎.github/steps/0-welcome.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<!-- readme -->

‎.github/steps/1-configure-label-based-job.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
## Step 1: Trigger a job based on labels
2+
3+
_Welcome to the course :tada:_
4+
5+
![Screen Shot 2022-06-07 at 4 01 43 PM](https://user-images.githubusercontent.com/6351798/172490466-00f27580-8906-471f-ae83-ef3b6370df7d.png)
6+
7+
A lot of things go into delivering "continuously". These things can range from culture and behavior to specific automation. In this exercise, we're going to focus on the deployment part of our automation.
8+
9+
In a GitHub Actions workflow, the `on` step defines what causes the workflow to run. In this case, we want the workflow to run different tasks when specific labels are applied to a pull request.
10+
11+
We'll use labels as triggers for multiple tasks:
12+
13+
- When someone applies a "spin up environment" label to a pull request, that'll tell GitHub Actions that we'd like to set up our resources on an Azure environment.
14+
- When someone applies a "stage" label to a pull request, that'll be our indicator that we'd like to deploy our application to a staging environment.
15+
- When someone applies a "destroy environment" label to a pull request, we'll tear down any resources that are running on our Azure account.
16+
17+
### :keyboard: Activity 1: Configure `GITHUB_TOKEN` permissions
18+
19+
At the start of each workflow run, GitHub automatically creates a unique `GITHUB_TOKEN` secret to use in your workflow. We need to make sure this token has the permissions required for this course.
20+
21+
1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
22+
1. Go to Settings > Actions > General. Ensure that the `GITHUB_TOKEN` also has **Read and write permissions** enabled under **Workflow permissions**. This is required for your workflow to be able to upload your image to the container registry.
23+
24+
### :keyboard: Activity 2: Configure a trigger based on labels
25+
26+
For now, we'll focus on staging. We'll spin up and destroy our environment in a later step.
27+
28+
1. Go to the **Actions** tab.
29+
1. Click **New workflow**
30+
1. Search for "simple workflow" and click **Configure**
31+
1. Name your workflow `deploy-staging.yml`
32+
1. Edit the contents of this file and remove all triggers and jobs.
33+
1. Edit the contents of the file to add a conditional that filters the `build` job when there is a label present called **stage**. Your resulting file should look like this:
34+
35+
```yaml
36+
name: Stage the app
37+
38+
on:
39+
pull_request:
40+
types: [labeled]
41+
42+
jobs:
43+
build:
44+
runs-on: ubuntu-latest
45+
46+
if: contains(github.event.pull_request.labels.*.name, 'stage')
47+
```
48+
49+
1. Click **Start commit**, and choose to make a new branch named `staging-workflow`.
50+
1. Click **Propose changes**.
51+
1. Click **Create pull request**.
52+
1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

‎.github/steps/2-setup-azure-environment.md

+182
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
## Step 2: Set up an Azure environment
2+
3+
_Good job getting started :gear:_
4+
5+
### Nice work triggering a job on specific labels
6+
7+
We won't be going into detail on the steps of this workflow, but it would be a good idea to become familiar with the actions we're using. They are:
8+
9+
- [`actions/checkout`](https://github.com/actions/checkout)
10+
- [`actions/upload-artifact`](https://github.com/actions/upload-artifact)
11+
- [`actions/download-artifact`](https://github.com/actions/download-artifact)
12+
- [`docker/login-action`](https://github.com/docker/login-action)
13+
- [`docker/build-push-action`](https://github.com/docker/build-push-action)
14+
- [`azure/login`](https://github.com/Azure/login)
15+
- [`azure/webapps-deploy`](https://github.com/Azure/webapps-deploy)
16+
17+
### :keyboard: Activity 1: Store your credentials in GitHub secrets and finish setting up your workflow
18+
19+
1. In a new tab, [create an Azure account](https://azure.microsoft.com/en-us/free/) if you don't already have one. If your Azure account is created through work, you may encounter issues accessing the necessary resources -- we recommend creating a new account for personal use and for this course.
20+
> **Note**: You may need a credit card to create an Azure account. If you're a student, you may also be able to take advantage of the [Student Developer Pack](https://education.github.com/pack) for access to Azure. If you'd like to continue with the course without an Azure account, Skills will still respond, but none of the deployments will work.
21+
1. Create a [new subscription](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription) in the Azure Portal.
22+
> **Note**: your subscription must be configured "Pay as you go" which will require you to enter billing information. This course will only use a few minutes from your free plan, but Azure requires the billing information.
23+
1. Install [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) on your machine.
24+
1. In your terminal, run:
25+
```shell
26+
az login
27+
```
28+
1. Copy the value of the `id:` field to a safe place. We'll call this `AZURE_SUBSCRIPTION_ID`. Here's an example of what it looks like:
29+
```shell
30+
[
31+
{
32+
"cloudName": "AzureCloud",
33+
"id": "f****a09-****-4d1c-98**-f**********c", # <-- Copy this id field
34+
"isDefault": true,
35+
"name": "some-subscription-name",
36+
"state": "Enabled",
37+
"tenantId": "********-a**c-44**-**25-62*******61",
38+
"user": {
39+
"name": "mdavis******@*********.com",
40+
"type": "user"
41+
}
42+
}
43+
]
44+
```
45+
1. In your terminal, run the command below.
46+
47+
````shell
48+
az ad sp create-for-rbac --name "GitHub-Actions" --role contributor \
49+
--scopes /subscriptions/{subscription-id} \
50+
--sdk-auth
51+
52+
# Replace {subscription-id} with the same id stored in AZURE_SUBSCRIPTION_ID.
53+
```
54+
55+
> **Note**: The `\` character works as a line break on Unix based systems. If you are on a Windows based system the `\` character will cause this command to fail. Place this command on a single line if you are using Windows.\*\*
56+
57+
````
58+
59+
1. Copy the entire contents of the command's response, we'll call this `AZURE_CREDENTIALS`. Here's an example of what it looks like:
60+
```shell
61+
{
62+
"clientId": "<GUID>",
63+
"clientSecret": "<GUID>",
64+
"subscriptionId": "<GUID>",
65+
"tenantId": "<GUID>",
66+
(...)
67+
}
68+
```
69+
1. Back on GitHub, click on this repository's **Secrets and variables > Actions** in the Settings tab.
70+
1. Click **New repository secret**
71+
1. Name your new secret **AZURE_SUBSCRIPTION_ID** and paste the value from the `id:` field in the first command.
72+
1. Click **Add secret**.
73+
1. Click **New repository secret** again.
74+
1. Name the second secret **AZURE_CREDENTIALS** and paste the entire contents from the second terminal command you entered.
75+
1. Click **Add secret**
76+
1. Go back to the Pull requests tab and in your pull request go to the **Files Changed** tab. Find and then edit the `.github/workflows/deploy-staging.yml` file to use some new actions.
77+
78+
The full workflow file, should look like this:
79+
80+
```yaml
81+
name: Deploy to staging
82+
83+
on:
84+
pull_request:
85+
types: [labeled]
86+
87+
env:
88+
IMAGE_REGISTRY_URL: ghcr.io
89+
###############################################
90+
### Replace <username> with GitHub username ###
91+
###############################################
92+
DOCKER_IMAGE_NAME: <username>-azure-ttt
93+
AZURE_WEBAPP_NAME: <username>-ttt-app
94+
###############################################
95+
96+
jobs:
97+
build:
98+
if: contains(github.event.pull_request.labels.*.name, 'stage')
99+
100+
runs-on: ubuntu-latest
101+
102+
steps:
103+
- uses: actions/checkout@v3
104+
- name: npm install and build webpack
105+
run: |
106+
npm install
107+
npm run build
108+
- uses: actions/upload-artifact@v3
109+
with:
110+
name: webpack artifacts
111+
path: public/
112+
113+
Build-Docker-Image:
114+
runs-on: ubuntu-latest
115+
needs: build
116+
name: Build image and store in GitHub Container Registry
117+
steps:
118+
- name: Checkout
119+
uses: actions/checkout@v3
120+
121+
- name: Download built artifact
122+
uses: actions/download-artifact@v3
123+
with:
124+
name: webpack artifacts
125+
path: public
126+
127+
- name: Log in to GHCR
128+
uses: docker/login-action@v2
129+
with:
130+
registry: ${{ env.IMAGE_REGISTRY_URL }}
131+
username: ${{ github.actor }}
132+
password: ${{ secrets.GITHUB_TOKEN }}
133+
134+
- name: Extract metadata (tags, labels) for Docker
135+
id: meta
136+
uses: docker/metadata-action@v4
137+
with:
138+
images: ${{env.IMAGE_REGISTRY_URL}}/${{ github.repository }}/${{env.DOCKER_IMAGE_NAME}}
139+
tags: |
140+
type=sha,format=long,prefix=
141+
142+
- name: Build and push Docker image
143+
uses: docker/build-push-action@v3
144+
with:
145+
context: .
146+
push: true
147+
tags: ${{ steps.meta.outputs.tags }}
148+
labels: ${{ steps.meta.outputs.labels }}
149+
150+
Deploy-to-Azure:
151+
runs-on: ubuntu-latest
152+
needs: Build-Docker-Image
153+
name: Deploy app container to Azure
154+
steps:
155+
- name: "Login via Azure CLI"
156+
uses: azure/login@v1
157+
with:
158+
creds: ${{ secrets.AZURE_CREDENTIALS }}
159+
160+
- uses: azure/docker-login@v1
161+
with:
162+
login-server: ${{env.IMAGE_REGISTRY_URL}}
163+
username: ${{ github.actor }}
164+
password: ${{ secrets.GITHUB_TOKEN }}
165+
166+
- name: Deploy web app container
167+
uses: azure/webapps-deploy@v2
168+
with:
169+
app-name: ${{env.AZURE_WEBAPP_NAME}}
170+
images: ${{env.IMAGE_REGISTRY_URL}}/${{ github.repository }}/${{env.DOCKER_IMAGE_NAME}}:${{ github.sha }}
171+
172+
- name: Azure logout via Azure CLI
173+
uses: azure/CLI@v1
174+
with:
175+
inlineScript: |
176+
az logout
177+
az cache purge
178+
az account clear
179+
```
180+
181+
16. After you've edited the file, click **Commit changes...** and commit to the `staging-workflow` branch.
182+
17. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

‎.github/steps/3-spinup-environment.md

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
## Step 3: Spin up an environment based on labels
2+
3+
_Nicely done! :heart:_
4+
5+
GitHub Actions is cloud agnostic, so any cloud will work. We'll show how to deploy to Azure in this course.
6+
7+
**What are _Azure resources_?** In Azure, a resource is an entity managed by Azure. We'll use the following Azure resources in this course:
8+
9+
- A [web app](https://docs.microsoft.com/en-us/azure/app-service/overview) is how we'll be deploying our application to Azure.
10+
- A [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups) is a collection of resources, like web apps and virtual machines (VMs).
11+
- An [App Service plan](https://docs.microsoft.com/en-us/azure/app-service/overview-hosting-plans) is what runs our web app and manages the billing (our app should run for free).
12+
13+
Through the power of GitHub Actions, we can create, configure, and destroy these resources through our workflow files.
14+
15+
### :keyboard: Activity 1: Set up a personal access token (PAT)
16+
17+
Personal access tokens (PATs) are an alternative to using passwords for authentication to GitHub. We will use a PAT to allow your web app to pull the container image after your workflow pushes a newly built image to the registry.
18+
19+
1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
20+
2. Create a personal access token with the `repo` and `read:packages` scopes. For more information, see ["Creating a personal access token."](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
21+
3. Once you have generated the token we will need to store it in a secret so that it can be used within a workflow. Create a new repository secret named `CR_PAT` and paste the PAT token in as the value.
22+
4. With this done we can move on to setting up our workflow.
23+
24+
**Configuring your Azure environment**
25+
26+
To deploy successfully to our Azure environment:
27+
28+
1. Create a new branch called `azure-configuration` by clicking on the branch dropdown on the top, left hand corner of the `Code` tab on your repository page.
29+
2. Once you're in the new `azure-configuration` branch, go into the `.github/workflows` directory and create a new file titled `spinup-destroy.yml` by clicking **Add file**.
30+
31+
Copy and paste the following into this new file:
32+
33+
```yaml
34+
name: Configure Azure environment
35+
36+
on:
37+
pull_request:
38+
types: [labeled]
39+
40+
env:
41+
IMAGE_REGISTRY_URL: ghcr.io
42+
AZURE_RESOURCE_GROUP: cd-with-actions
43+
AZURE_APP_PLAN: actions-ttt-deployment
44+
AZURE_LOCATION: '"Central US"'
45+
###############################################
46+
### Replace <username> with GitHub username ###
47+
###############################################
48+
AZURE_WEBAPP_NAME: <username>-ttt-app
49+
50+
jobs:
51+
setup-up-azure-resources:
52+
runs-on: ubuntu-latest
53+
if: contains(github.event.pull_request.labels.*.name, 'spin up environment')
54+
steps:
55+
- name: Checkout repository
56+
uses: actions/checkout@v3
57+
58+
- name: Azure login
59+
uses: azure/login@v1
60+
with:
61+
creds: ${{ secrets.AZURE_CREDENTIALS }}
62+
63+
- name: Create Azure resource group
64+
if: success()
65+
run: |
66+
az group create --location ${{env.AZURE_LOCATION}} --name ${{env.AZURE_RESOURCE_GROUP}} --subscription ${{secrets.AZURE_SUBSCRIPTION_ID}}
67+
68+
- name: Create Azure app service plan
69+
if: success()
70+
run: |
71+
az appservice plan create --resource-group ${{env.AZURE_RESOURCE_GROUP}} --name ${{env.AZURE_APP_PLAN}} --is-linux --sku F1 --subscription ${{secrets.AZURE_SUBSCRIPTION_ID}}
72+
73+
- name: Create webapp resource
74+
if: success()
75+
run: |
76+
az webapp create --resource-group ${{ env.AZURE_RESOURCE_GROUP }} --plan ${{ env.AZURE_APP_PLAN }} --name ${{ env.AZURE_WEBAPP_NAME }} --deployment-container-image-name nginx --subscription ${{secrets.AZURE_SUBSCRIPTION_ID}}
77+
78+
- name: Configure webapp to use GHCR
79+
if: success()
80+
run: |
81+
az webapp config container set --docker-custom-image-name nginx --docker-registry-server-password ${{secrets.CR_PAT}} --docker-registry-server-url https://${{env.IMAGE_REGISTRY_URL}} --docker-registry-server-user ${{github.actor}} --name ${{ env.AZURE_WEBAPP_NAME }} --resource-group ${{ env.AZURE_RESOURCE_GROUP }} --subscription ${{secrets.AZURE_SUBSCRIPTION_ID}}
82+
83+
destroy-azure-resources:
84+
runs-on: ubuntu-latest
85+
86+
if: contains(github.event.pull_request.labels.*.name, 'destroy environment')
87+
88+
steps:
89+
- name: Checkout repository
90+
uses: actions/checkout@v3
91+
92+
- name: Azure login
93+
uses: azure/login@v1
94+
with:
95+
creds: ${{ secrets.AZURE_CREDENTIALS }}
96+
97+
- name: Destroy Azure environment
98+
if: success()
99+
run: |
100+
az group delete --name ${{env.AZURE_RESOURCE_GROUP}} --subscription ${{secrets.AZURE_SUBSCRIPTION_ID}} --yes
101+
```
102+
103+
3. Click **Commit changes...** and select `Commit directly to the azure-configuration branch.` before clicking **Commit changes**.
104+
4. Go to the Pull requests tab of the repository.
105+
5. There should be a yellow banner with the `azure-configuration` branch where you can click **Compare & pull request**.
106+
6. Set the title of the Pull request to: `Added spinup-destroy.yml workflow` and click `Create pull request`.
107+
108+
We will cover the key functionality below and then put the workflow to use by applying a label to the pull request.
109+
110+
This new workflow has two jobs:
111+
112+
1. **Set up Azure resources** will run if the pull request contains a label with the name "spin up environment".
113+
2. **Destroy Azure resources** will run if the pull request contains a label with the name "destroy environment".
114+
115+
In addition to each job, there's a few global environment variables:
116+
117+
- `AZURE_RESOURCE_GROUP`, `AZURE_APP_PLAN`, and `AZURE_WEBAPP_NAME` are names for our resource group, app service plan, and web app, respectively, which we'll reference over multiple steps and workflows
118+
- `AZURE_LOCATION` lets us specify the [region](https://azure.microsoft.com/en-us/global-infrastructure/regions/) for the data centers, where our app will ultimately be deployed.
119+
120+
**Setting up Azure resources**
121+
122+
The first job sets up the Azure resources as follows:
123+
124+
1. Logs into your Azure account with the [`azure/login`](https://github.com/Azure/login) action. The `AZURE_CREDENTIALS` secret you created earlier is used for authentication.
125+
1. Creates an [Azure resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups) by running [`az group create`](https://docs.microsoft.com/en-us/cli/azure/group?view=azure-cli-latest#az-group-create) on the Azure CLI, which is [pre-installed on the GitHub-hosted runner](https://help.github.com/en/actions/reference/software-installed-on-github-hosted-runners).
126+
1. Creates an [App Service plan](https://docs.microsoft.com/en-us/azure/app-service/overview-hosting-plans) by running [`az appservice plan create`](https://docs.microsoft.com/en-us/cli/azure/appservice/plan?view=azure-cli-latest#az-appservice-plan-create) on the Azure CLI.
127+
1. Creates a [web app](https://docs.microsoft.com/en-us/azure/app-service/overview) by running [`az webapp create`](https://docs.microsoft.com/en-us/cli/azure/webapp?view=azure-cli-latest#az-webapp-create) on the Azure CLI.
128+
1. Configures the newly created web app to use [GitHub Packages](https://help.github.com/en/packages/publishing-and-managing-packages/about-github-packages) by using [`az webapp config`](https://docs.microsoft.com/en-us/cli/azure/webapp/config?view=azure-cli-latest) on the Azure CLI. Azure can be configured to use its own [Azure Container Registry](https://docs.microsoft.com/en-us/azure/container-registry/), [DockerHub](https://docs.docker.com/docker-hub/), or a custom (private) registry. In this case, we'll configure GitHub Packages as a custom registry.
129+
130+
**Destroying Azure resources**
131+
132+
The second job destroys Azure resources so that you do not use your free minutes or incur billing. The job works as follows:
133+
134+
1. Logs into your Azure account with the [`azure/login`](https://github.com/Azure/login) action. The `AZURE_CREDENTIALS` secret you created earlier is used for authentication.
135+
1. Deletes the resource group we created earlier using [`az group delete`](https://docs.microsoft.com/en-us/cli/azure/group?view=azure-cli-latest#az-group-delete) on the Azure CLI.
136+
137+
### :keyboard: Activity 2: Apply labels to create resources
138+
139+
1. Edit the `spinup-destroy.yml` file in your open pull request and replace any `<username>` placeholders with your GitHub username. Commit this change directly to the `azure-configuration` branch.
140+
1. Back in the Pull request, create and apply the `spin up environment` label to your open pull request
141+
1. Wait for the GitHub Actions workflow to run and spin up your Azure environment. You can follow along in the Actions tab or in the pull request merge box.
142+
1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

0 commit comments

Comments
 (0)