Skip to content

Commit 83af0af

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #114121 from craigshoemaker/marmalade-actions
[New article] Add GitHub Actions workflow article
2 parents 894863e + 9594c1a commit 83af0af

File tree

2 files changed

+166
-0
lines changed

2 files changed

+166
-0
lines changed

‎articles/static-apps/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@
2323
href: review-publish-pull-requests.md
2424
- name: Custom domain
2525
href: custom-domain.md
26+
- name: Build configuration
27+
href: github-actions-workflow.md
2628
- name: How-to guides
2729
items:
2830
- name: Setup local development

‎articles/static-apps/github-actions-workflow.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: GitHub Actions workflows for Azure Static Web Apps
3+
description: Learn how to use GitHub repositories to set up continuous deployment to Azure Static Web Apps.
4+
services: static-web-apps
5+
author: christiannwamba
6+
ms.service: static-web-apps
7+
ms.topic: conceptual
8+
ms.date: 05/08/2020
9+
ms.author: chnwamba
10+
---
11+
12+
# GitHub Actions workflows for Azure Static Web Apps
13+
14+
When you create a new Azure Static Web App resource, Azure generates a GitHub Actions workflow to control the app's continuous deployment. The workflow is driven by a YAML file. This article details the structure and options of the workflow file.
15+
16+
Deployments are initiated by [triggers](#triggers), which run [jobs](#jobs) that are defined by individual [steps](#steps).
17+
18+
## File location
19+
20+
When you link your GitHub repository to Azure Static Web Apps, a workflow file is added to the repository.
21+
22+
Follow these steps to view the generated workflow file.
23+
24+
1. Open the app's repository on GitHub.
25+
1. From the _Code_ tab, click on the `.github/workflows` folder.
26+
1. Click on the file with a name that looks like `azure-static-web-apps-<RANDOM_NAME>.yml`.
27+
28+
The YAML file in your repository will be similar to the following example:
29+
30+
```yml
31+
name: Azure Static Web Apps CI/CD
32+
33+
on:
34+
push:
35+
branches:
36+
- master
37+
pull_request:
38+
types: [opened, synchronize, reopened, closed]
39+
branches:
40+
- master
41+
42+
jobs:
43+
build_and_deploy_job:
44+
if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
45+
runs-on: ubuntu-latest
46+
name: Build and Deploy Job
47+
steps:
48+
- uses: actions/checkout@v1
49+
- name: Build And Deploy
50+
id: builddeploy
51+
uses: Azure/static-web-apps-deploy@master
52+
with:
53+
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
54+
repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
55+
action: 'upload'
56+
###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
57+
app_location: '/' # App source code path
58+
api_location: 'api' # Api source code path - optional
59+
app_artifact_location: 'dist' # Built app content directory - optional
60+
###### End of Repository/Build Configurations ######
61+
62+
close_pull_request_job:
63+
if: github.event_name == 'pull_request' && github.event.action == 'closed'
64+
runs-on: ubuntu-latest
65+
name: Close Pull Request Job
66+
steps:
67+
- name: Close Pull Request
68+
id: closepullrequest
69+
uses: Azure/static-web-apps-deploy@master
70+
with:
71+
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
72+
action: 'close'
73+
```
74+
75+
## Triggers
76+
77+
A GitHub Actions [trigger](https://help.github.com/actions/reference/events-that-trigger-workflows) notifies a GitHub Actions workflow to run a job based off event triggers. Triggers are listed using the `on` property in the workflow file.
78+
79+
```yml
80+
on:
81+
push:
82+
branches:
83+
- master
84+
pull_request:
85+
types: [opened, synchronize, reopened, closed]
86+
branches:
87+
- master
88+
```
89+
90+
Through settings associated with the `on` property, you can define which branches trigger a job, and set triggers to fire for different pull request states.
91+
92+
In this example, a workflow is started as the _master_ branch changes. Changes that start the workflow include pushing commits and opening pull requests against the chosen branch.
93+
94+
## Jobs
95+
96+
Each event trigger requires an event handler. [Jobs](https://help.github.com/actions/reference/workflow-syntax-for-github-actions#jobs) define what happens when an event is triggered.
97+
98+
In the Static Web Apps workflow file, there are two available jobs.
99+
100+
| Name | Description |
101+
|---------|---------|
102+
|`build_and_deploy_job` | Executes when you push commits or open a pull request against the branch listed in the `on` property. |
103+
|`close_pull_request_job` | Executes ONLY when you close a pull request. |
104+
105+
## Steps
106+
107+
Steps are sequential tasks for a job. A step carries out actions like installing dependencies, running tests, and deploying your application to production.
108+
109+
A workflow file defines the following steps.
110+
111+
| Job | Steps |
112+
|---------|---------|
113+
| `build_and_deploy_job` |<ol><li>Checks out the repository in the Action's environment.<li>Builds and deploys the repository to Azure Static Web Apps.</ol>|
114+
| `close_pull_request_job` | <ol><li>Notifies Azure Static Web Apps that a pull request has closed.</ol>|
115+
116+
## Build and deploy
117+
118+
The step named `Build and Deploy` builds and deploys to your Azure Static Web Apps instance. Under the `with` section, you can customize the following values for your deployment.
119+
120+
```yml
121+
with:
122+
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_MANGO_RIVER_0AFDB141E }}
123+
repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
124+
action: 'upload'
125+
###### Repository/Build Configurations - These values can be configured to match you app requirements. ######
126+
app_location: '/' # App source code path
127+
api_location: 'api' # Api source code path - optional
128+
app_artifact_location: 'dist' # Built app content directory - optional
129+
###### End of Repository/Build Configurations ######
130+
```
131+
132+
| Property | Description | Required |
133+
|---|---|---|
134+
| `app_location` | Location of your application code.<br><br>For example, enter `/` if your application source code is at the root of the repository, or `/app` if your application code is in a directory called `app`. | Yes |
135+
| `api_location` | Location of your Azure Functions code.<br><br>For example, enter `/api` if your app code is in a folder called `api`. If no Azure Functions app is detected in the folder, the build doesn't fail, the workflow assumes you do not want an API. | No |
136+
| `app_artifact_location` | Location of the build output directory relative to the `app_location`.<br><br>For example, if your application source code is located at `/app`, and the build script outputs files to the `/app/build` folder, then set `build` as the `app_artifact_location` value. | No |
137+
138+
The `repo_token`, `action`, and `azure_static_web_apps_api_token` values are set for you by Azure Static Web Apps shouldn't be manually changed.
139+
140+
## Customizations
141+
142+
There are few additional configuration settings available that are not generated in the workflow file by default.
143+
144+
### Custom build commands
145+
146+
You can have fine-grained control over what commands run during a deployment.
147+
148+
The deployment always calls `npm install` before any custom command.
149+
150+
| Command | Description |
151+
|---------------------|-------------|
152+
| `app_build_command` | Defines a custom command to run during deployment of the static content application.<br><br>For example, to configure a production build for an Angular application enter `ng build -prod`. |
153+
| `api_build_command` | Defines a custom command to run during deployment of the Azure Functions API application. |
154+
155+
### Route file location
156+
157+
You can customize the workflow to look for the [routes.json](routes.md) in any folder in your repository. The `routes_location` property defines the directory location where the _routes.json_ file is found. This location is relative to the root of the repository.
158+
159+
Being explicit about the location of your _routes.json_ file is particularly important if your front-end framework build step does not move this file to the `app_artifact_location` by default.
160+
161+
## Next steps
162+
163+
> [!div class="nextstepaction"]
164+
> [Review pull requests in pre-production environments](review-publish-pull-requests.md)

0 commit comments

Comments
 (0)