Skip to content

Commit 732707c

Browse files
craigshoemakercraigshoemaker
committed
add zone pivots
1 parent 8d2d6de commit 732707c

File tree

2 files changed

+155
-61
lines changed

2 files changed

+155
-61
lines changed

‎articles/static-web-apps/build-configuration.md

Lines changed: 146 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@ services: static-web-apps
55
author: craigshoemaker
66
ms.service: azure-static-web-apps
77
ms.topic: conceptual
8-
ms.date: 10/29/2024
8+
ms.date: 10/30/2024
99
ms.author: cshoe
10+
zone_pivot_groups: static-web-apps-ci-cd
1011
---
1112

1213
# Build configuration for Azure Static Web Apps
@@ -31,15 +32,31 @@ With these settings, you can set up GitHub Actions or [Azure Pipelines](get-star
3132

3233
## File name and location
3334

34-
# [GitHub Actions](#tab/github-actions)
35+
<!--
36+
::: zone pivot="azure-pipelines"
37+
38+
39+
40+
::: zone-end
41+
42+
::: zone pivot="github-actions"
43+
44+
45+
46+
::: zone-end
47+
-->
48+
49+
::: zone pivot="azure-pipelines"
3550

3651
The GitHub action generates the configuration file and is stored in the *.github/workflows* folder, named using the following format: `azure-static-web-apps-<RANDOM_NAME>.yml`.
3752

38-
# [Azure Pipelines](#tab/azure-devops)
53+
::: zone-end
54+
55+
::: zone pivot="github-actions"
3956

4057
By default, the configuration file is stored at the root of your repository with the name `azure-pipelines.yml`.
4158

42-
---
59+
::: zone-end
4360

4461
## Security
4562

@@ -58,7 +75,44 @@ The following sample configuration monitors the repository for changes. As commi
5875
> [!NOTE]
5976
> This example shows a sample configuration that uses an Azure deployment token to secure the build configuration.
6077
61-
# [GitHub Actions](#tab/github-actions)
78+
::: zone pivot="azure-pipelines"
79+
80+
```yaml
81+
trigger:
82+
- main
83+
84+
pool:
85+
vmImage: ubuntu-latest
86+
87+
steps:
88+
- checkout: self
89+
submodules: true
90+
- task: AzureStaticWebApp@0
91+
inputs:
92+
app_location: 'src' # App source code path relative to cwd
93+
api_location: 'api' # Api source code path relative to cwd
94+
output_location: 'public' # Built app content directory relative to app_location - optional
95+
cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
96+
azure_static_web_apps_api_token: $(deployment_token)
97+
```
98+
99+
In this configuration:
100+
101+
- The `main` branch is monitored for commits.
102+
- The `app_location` points to the `src` folder that contains the source files for the web app. This value is relative to the working directory (`cwd`). To set it to the working directory, use `/`.
103+
- The `api_location` points to the `api` folder that contains the Azure Functions application for the site's API endpoints. This value is relative to the working directory (`cwd`). To set it to the working directory, use `/`.
104+
- The `output_location` points to the `public` folder that contains the final version of the app's source files. This value is relative to `app_location`. For .NET projects, the location is relative to the output folder.
105+
- The `cwd` is an absolute path pointing to the working directory. It defaults to `$(System.DefaultWorkingDirectory)`.
106+
- The `$(deployment_token)` variable points to the [generated Azure DevOps deployment token](./deployment-token-management.md).
107+
108+
> [!NOTE]
109+
> `app_location` and `api_location` must be relative to the working directory (`cwd`) and they must be subdirectories under `cwd`.
110+
111+
::: zone-end
112+
113+
::: zone pivot="github-actions"
114+
115+
# [Azure deployment token](#tab/adt)
62116

63117
```yml
64118
name: Azure Static Web Apps CI/CD
@@ -124,12 +178,62 @@ jobs:
124178
action: "close"
125179
```
126180

181+
# [GitHub access token](#tab/gat)
182+
183+
```yml
184+
name: Azure Static Web Apps CI/CD
185+
186+
on:
187+
push:
188+
branches:
189+
- main
190+
pull_request:
191+
types: [opened, synchronize, reopened, closed]
192+
branches:
193+
- main
194+
195+
jobs:
196+
build_and_deploy_job:
197+
if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
198+
runs-on: ubuntu-latest
199+
name: Build and Deploy Job
200+
steps:
201+
- uses: actions/checkout@v2
202+
with:
203+
submodules: true
204+
- name: Build And Deploy
205+
id: builddeploy
206+
uses: Azure/static-web-apps-deploy@v1
207+
with:
208+
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
209+
repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
210+
action: "upload"
211+
###### Repository/Build Configurations ######
212+
app_location: "src" # App source code path relative to repository root
213+
api_location: "api" # Api source code path relative to repository root - optional
214+
output_location: "public" # Built app content directory, relative to app_location - optional
215+
###### End of Repository/Build Configurations ######
216+
217+
close_pull_request_job:
218+
if: github.event_name == 'pull_request' && github.event.action == 'closed'
219+
runs-on: ubuntu-latest
220+
name: Close Pull Request Job
221+
steps:
222+
- name: Close Pull Request
223+
id: closepullrequest
224+
uses: Azure/static-web-apps-deploy@v1
225+
with:
226+
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
227+
action: "close"
228+
```
229+
230+
---
231+
127232
In this configuration:
128233

129234
- The `main` branch is monitored for commits.
130235
- A GitHub Actions workflow is [triggered](https://help.github.com/actions/reference/events-that-trigger-workflows) when a pull request on the `main` branch is: opened, synchronized, reopened, or closed.
131236
- The `build_and_deploy_job` executes when you push commits or open a pull request against the branch listed in the `on` property.
132-
- One of the `steps` makes an `idtoken` available to authenticate the build process with Azure services.
133237
- The `app_location` points to the `src` folder that contains the source files for the web app. To set this value to the repository root, use `/`.
134238
- The `api_location` points to the `api` folder that contains the Azure Functions application for the site's API endpoints. To set this value to the repository root, use `/`.
135239
- The `output_location` points to the `public` folder that contains the final version of the app's source files. It's relative to `app_location`. For .NET projects, the location is relative to the publish output folder.
@@ -144,40 +248,7 @@ This job helps keep your pull request workflow organized and prevents stale pull
144248

145249
The *Close Pull Request* job is part of the Azure Static Web Apps GitHub Actions workflow, closing the pull request after it's merged. The `Azure/static-web-apps-deploy` action deploys the app to Azure Static Web Apps, requiring the `azure_static_web_apps_api_token` for authentication.
146250

147-
# [Azure Pipelines](#tab/azure-devops)
148-
149-
```yaml
150-
trigger:
151-
- main
152-
153-
pool:
154-
vmImage: ubuntu-latest
155-
156-
steps:
157-
- checkout: self
158-
submodules: true
159-
- task: AzureStaticWebApp@0
160-
inputs:
161-
app_location: 'src' # App source code path relative to cwd
162-
api_location: 'api' # Api source code path relative to cwd
163-
output_location: 'public' # Built app content directory relative to app_location - optional
164-
cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
165-
azure_static_web_apps_api_token: $(deployment_token)
166-
```
167-
168-
In this configuration:
169-
170-
- The `main` branch is monitored for commits.
171-
- The `app_location` points to the `src` folder that contains the source files for the web app. This value is relative to the working directory (`cwd`). To set it to the working directory, use `/`.
172-
- The `api_location` points to the `api` folder that contains the Azure Functions application for the site's API endpoints. This value is relative to the working directory (`cwd`). To set it to the working directory, use `/`.
173-
- The `output_location` points to the `public` folder that contains the final version of the app's source files. This value is relative to `app_location`. For .NET projects, the location is relative to the output folder.
174-
- The `cwd` is an absolute path pointing to the working directory. It defaults to `$(System.DefaultWorkingDirectory)`.
175-
- The `$(deployment_token)` variable points to the [generated Azure DevOps deployment token](./deployment-token-management.md).
176-
177-
> [!NOTE]
178-
> `app_location` and `api_location` must be relative to the working directory (`cwd`) and they must be subdirectories under `cwd`.
179-
180-
---
251+
::: zone-end
181252

182253
## Custom build commands
183254

@@ -187,7 +258,7 @@ For Node.js applications, you can take fine-grained control over what commands r
187258
> Currently, you can only define `app_build_command` and `api_build_command` for Node.js builds.
188259
> To specify the Node.js version, use the [`engines`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#engines) field in the `package.json` file.
189260

190-
# [GitHub Actions](#tab/github-actions)
261+
::: zone pivot="github-actions"
191262

192263
```yml
193264
...
@@ -203,7 +274,9 @@ with:
203274
api_build_command: 'npm run build-api-prod'
204275
```
205276

206-
# [Azure Pipelines](#tab/azure-devops)
277+
::: zone-end
278+
279+
::: zone pivot="azure-pipelines"
207280

208281
```yaml
209282
...
@@ -217,7 +290,7 @@ inputs:
217290
azure_static_web_apps_api_token: $(deployment_token)
218291
```
219292

220-
---
293+
::: zone-end
221294

222295
## Skip building front-end app
223296

@@ -232,7 +305,7 @@ To skip building the front-end app:
232305
> [!NOTE]
233306
> Make sure you have your `staticwebapp.config.json` file copied as well into the *output* directory.
234307

235-
# [GitHub Actions](#tab/github-actions)
308+
::: zone pivot="github-actions"
236309

237310
```yml
238311
...
@@ -247,7 +320,9 @@ with:
247320
skip_app_build: true
248321
```
249322

250-
# [Azure Pipelines](#tab/azure-devops)
323+
::: zone-end
324+
325+
::: zone pivot="azure-pipelines"
251326

252327
```yml
253328
...
@@ -260,7 +335,7 @@ inputs:
260335
azure_static_web_apps_api_token: $(deployment_token)
261336
```
262337

263-
---
338+
::: zone-end
264339

265340
## Skip building the API
266341

@@ -281,7 +356,7 @@ Steps to skip building the API:
281356
- Set `skip_api_build` to `true`.
282357
- Set `api_location` to the folder containing the built API app to deploy. This path is relative to the repository root in GitHub Actions and `cwd` in Azure Pipelines.
283358

284-
# [GitHub Actions](#tab/github-actions)
359+
::: zone pivot="github-actions"
285360

286361
```yml
287362
...
@@ -296,7 +371,9 @@ with:
296371
skip_api_build: true
297372
```
298373

299-
# [Azure Pipelines](#tab/azure-devops)
374+
::: zone-end
375+
376+
::: zone pivot="azure-pipelines"
300377

301378
```yml
302379
...
@@ -309,13 +386,13 @@ inputs:
309386
azure_static_web_apps_api_token: $(deployment_token)
310387
```
311388

312-
---
389+
::: zone-end
313390

314391
## Extend build timeout
315392

316393
By default, the app and API builds are limited to 15 minutes. You can extend the build timeout by setting the `build_timeout_in_minutes` property.
317394

318-
# [GitHub Actions](#tab/github-actions)
395+
::: zone pivot="github-actions"
319396

320397
```yaml
321398
...
@@ -330,7 +407,9 @@ with:
330407
build_timeout_in_minutes: 30
331408
```
332409

333-
# [Azure Pipelines](#tab/azure-devops)
410+
::: zone-end
411+
412+
::: zone pivot="azure-pipelines"
334413

335414
```yml
336415
...
@@ -343,15 +422,15 @@ inputs:
343422
azure_static_web_apps_api_token: $(deployment_token)
344423
```
345424

346-
---
425+
::: zone-end
347426

348427
## Run workflow without deployment secrets
349428

350429
Sometimes you need your workflow to continue to process even when some secrets are missing. To configure your workflow to proceed without defined secrets, set the `SKIP_DEPLOY_ON_MISSING_SECRETS` environment variable to `true`.
351430

352431
When enabled, this feature allows the workflow to continue without deploying the site's content.
353432

354-
# [GitHub Actions](#tab/github-actions)
433+
::: zone pivot="github-actions"
355434

356435
```yaml
357436
...
@@ -367,7 +446,9 @@ env:
367446
SKIP_DEPLOY_ON_MISSING_SECRETS: true
368447
```
369448

370-
# [Azure Pipelines](#tab/azure-devops)
449+
::: zone-end
450+
451+
::: zone pivot="azure-pipelines"
371452

372453
```yaml
373454
...
@@ -381,15 +462,15 @@ env:
381462
SKIP_DEPLOY_ON_MISSING_SECRETS: true
382463
```
383464

384-
---
465+
::: zone-end
385466

386467
## Environment variables
387468

388469
You can set environment variables for your build via the `env` section of a job's configuration.
389470

390471
For more information about the environment variables used by Oryx, see [Oryx configuration](https://github.com/microsoft/Oryx/blob/main/doc/configuration.md).
391472

392-
# [GitHub Actions](#tab/github-actions)
473+
::: zone pivot="github-actions"
393474

394475
```yaml
395476
...
@@ -405,7 +486,9 @@ env: # Add environment variables here
405486
HUGO_VERSION: 0.58.0
406487
```
407488

408-
# [Azure Pipelines](#tab/azure-devops)
489+
::: zone-end
490+
491+
::: zone pivot="azure-pipelines"
409492

410493
```yml
411494
...
@@ -419,15 +502,15 @@ env: # Add environment variables here
419502
HUGO_VERSION: 0.58.0
420503
```
421504

422-
---
505+
::: zone-end
423506

424507
## Monorepo support
425508

426509
A monorepo is a repository that contains code for more than one application. By default, the workflow tracks all files in a repository, but you can adjust the configuration to target a single app.
427510

428511
To target a workflow file to a single app, you specify paths in the `push` and `pull_request` sections.
429512

430-
# [GitHub Actions](#tab/github-actions)
513+
::: zone pivot="github-actions"
431514

432515
When you set up a monorepo, each static app configuration is scoped to only files for a single app. The different workflow files live side by side in the repository's _.github/workflows_ folder.
433516

@@ -473,11 +556,13 @@ In this example, only changes made to following files trigger a new build:
473556
- Any files inside the _api1_ folder
474557
- Changes to the app's _azure-static-web-apps-purple-pond.yml_ workflow file
475558

476-
# [Azure Pipelines](#tab/azure-devops)
559+
::: zone-end
560+
561+
::: zone pivot="azure-pipelines"
477562

478563
To support more than one application in a single repository, create a separate workflow file and associate it with different Azure Pipelines.
479564

480-
---
565+
::: zone-end
481566

482567
## Next steps
483568

0 commit comments

Comments
 (0)