Azure Static Web Apps에 대한 빌드 구성
Azure Static Web Apps 빌드 구성은 GitHub Actions 또는 Azure Pipelines에서 구동됩니다. 각 사이트에는 사이트를 빌드하고 배포하는 방법을 제어하는 YAML 구성 파일이 있습니다. 이 문서에서는 파일의 구조 및 옵션에 대해 설명합니다.
다음 표에서는 사용 가능한 구성 설정을 나열합니다.
| 속성 | 설명 | 필수 |
|---|---|---|
app_location |
이 폴더에는 프런트 엔드 애플리케이션의 소스 코드가 포함되어 있습니다. 값은 GitHub의 리포지토리 루트 및 Azure DevOps의 현재 작업 폴더와 관계가 있습니다. skip_app_build: true와 함께 사용할 경우 이 값은 앱의 빌드 출력 위치입니다. |
예 |
api_location |
이는 API 애플리케이션의 소스 코드가 포함되어 있는 폴더입니다. 값은 GitHub의 리포지토리 루트 및 Azure DevOps의 현재 작업 폴더와 관계가 있습니다. skip_api_build: true와 함께 사용할 경우 이 값은 API의 빌드 출력 위치입니다. |
아니요 |
output_location |
웹앱이 빌드 단계를 실행하는 경우 출력 위치는 공용 파일이 생성되는 폴더입니다. 대부분의 프로젝트에서 output_location은 app_location과 관계가 있습니다. 단, .NET 프로젝트의 경우 위치는 게시 출력 폴더와 관계가 있습니다. |
아니요 |
app_build_command |
Node.js 애플리케이션의 경우 사용자 지정 명령을 정의하여 정적 콘텐츠 애플리케이션을 빌드할 수 있습니다. 예를 들어 Angular 애플리케이션에 대한 프로덕션 빌드를 구성하려면 build-prod라는 이름의 npm 스크립트를 만들어 ng build --prod를 실행하고 npm run build-prod를 사용자 지정 명령으로 입력합니다. 이를 비워 두면 워크플로에서 npm run build 또는 npm run build:azure 명령을 실행하려고 시도합니다. |
아니요 |
api_build_command |
Node.js 애플리케이션의 경우 사용자 지정 명령을 정의하여 Azure Functions API 애플리케이션을 빌드할 수 있습니다. | 아니요 |
skip_app_build |
프런트 엔드 앱 빌드를 건너뛰려면 값을 true로 설정합니다. |
아니요 |
skip_api_build |
API 함수 빌드를 건너뛰려면 값을 true로 설정합니다. |
아니요 |
cwd(Azure Pipelines만 해당) |
작업 폴더의 절대 경로입니다. 기본값은 $(System.DefaultWorkingDirectory)입니다. |
아니요 |
build_timeout_in_minutes |
빌드 시간 제한을 사용자 지정하려면 이 값을 설정합니다. 기본값은 15입니다. |
아니요 |
이러한 설정을 사용하면 정적 웹앱에 대한 CI/CD(연속 통합/지속적인 업데이트)를 실행하도록 GitHub Actions 또는 Azure Pipelines를 설정할 수 있습니다.
파일 이름 및 위치
구성 파일은 GitHub에서 생성되고 azure-static-web-apps-<RANDOM_NAME>.yml 형식을 사용하여 이름이 .github/workflows인 폴더에 저장됩니다.
빌드 구성
다음 샘플 구성은 리포지토리의 변경 내용을 모니터링합니다. 커밋이 main 분기에 푸시되면 애플리케이션이 app_location 폴더에서 빌드되고 output_location의 파일이 공용 웹에 제공됩니다. 또한 api 폴더의 애플리케이션은 사이트의 api 경로에서 사용할 수 있습니다.
name: Azure Static Web Apps CI/CD
on:
push:
branches:
- main
pull_request:
types: [opened, synchronize, reopened, closed]
branches:
- main
jobs:
build_and_deploy_job:
if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
runs-on: ubuntu-latest
name: Build and Deploy Job
steps:
- uses: actions/checkout@v2
with:
submodules: true
- name: Build And Deploy
id: builddeploy
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
action: "upload"
###### Repository/Build Configurations ######
app_location: "src" # App source code path relative to repository root
api_location: "api" # Api source code path relative to repository root - optional
output_location: "public" # Built app content directory, relative to app_location - optional
###### End of Repository/Build Configurations ######
close_pull_request_job:
if: github.event_name == 'pull_request' && github.event.action == 'closed'
runs-on: ubuntu-latest
name: Close Pull Request Job
steps:
- name: Close Pull Request
id: closepullrequest
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
action: "close"
이 구성에서:
main분기는 커밋에 대해 모니터링됩니다.main분기의 끌어오기 요청이 열리거나, 동기화되거나, 다시 열리거나, 닫힌 경우 GitHub Actions 워크플로가 트리거됩니다.- 커밋을 푸시하거나
on속성에 나열된 분기에 대해 끌어오기 요청을 열 때build_and_deploy_job이 실행됩니다. app_location은 웹앱의 원본 파일이 포함된src폴더를 가리킵니다. 이 값을 리포지토리 루트로 설정하려면/를 사용합니다.api_location은 사이트의 API 엔드포인트에 대한 Azure Functions 애플리케이션이 포함된api폴더를 가리킵니다. 이 값을 리포지토리 루트로 설정하려면/를 사용합니다.output_location은 앱의 원본 파일의 최종 버전을 포함하는public폴더를 가리킵니다.app_location과 관계가 있습니다. 단, .NET 프로젝트의 경우 위치는 게시 출력 폴더와 관계가 있습니다.
repo_token, action 및 azure_static_web_apps_api_token의 값은 Azure Static Web Apps에서 설정되므로 변경하지 마세요.
사용자 지정 빌드 명령
Node.js 애플리케이션의 경우 앱 또는 API 빌드 프로세스 중에 실행되는 명령을 세부적으로 제어할 수 있습니다. 다음 예제에서는 app_build_command 및 api_build_command에 대한 값을 사용하여 빌드를 정의하는 방법을 보여 줍니다.
참고 항목
현재는 Node.js 빌드에 대한 app_build_command 및 api_build_command만 정의할 수 있습니다.
Node.js 버전을 지정하려면 package.json 파일의 engines 필드를 사용합니다.
...
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: 'upload'
app_location: '/'
api_location: 'api'
output_location: 'dist'
app_build_command: 'npm run build-ui-prod'
api_build_command: 'npm run build-api-prod'
프런트 엔드 앱 빌드 건너뛰기
프런트 엔드 앱에 대한 빌드를 완전히 제어해야 하는 경우 자동 빌드를 무시하고 이전 단계에서 빌드된 앱을 배포할 수 있습니다.
프런트 엔드 앱 빌드를 건너뛰려면 다음을 수행합니다.
app_location을 배포할 파일 위치로 설정합니다.skip_app_build를true로 설정합니다.output_location을 빈 문자열('')로 설정합니다.
참고 항목
staticwebapp.config.json 파일을 출력 디렉터리로 복사했는지 확인합니다.
...
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: 'upload'
app_location: 'src/dist'
api_location: 'api'
output_location: ''
skip_app_build: true
API 빌드 건너뛰기
API 빌드를 건너뛰려면 자동 빌드를 무시하고 이전 단계에서 빌드된 API를 배포할 수 있습니다.
API 빌드를 건너뛰는 단계:
- staticwebapp.config.json 파일에서
apiRuntime을 올바른 런타임 및 버전으로 설정합니다. 지원되는 런타임 및 버전 목록은 Azure Static Web Apps 구성을 참조하세요.{ "platform": { "apiRuntime": "node:16" } } skip_api_build를true로 설정합니다.api_location을 배포할 빌드된 API 앱이 포함된 폴더로 설정합니다. 이 경로는 GitHub Actions의 리포지토리 루트 및 Azure Pipelines의cwd와 관계가 있습니다.
...
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: 'upload'
app_location: "src" # App source code path relative to repository root
api_location: "api" # Api source code path relative to repository root - optional
output_location: "public" # Built app content directory, relative to app_location - optional
skip_api_build: true
빌드 시간 제한 연장
기본적으로 앱 및 API 빌드는 15분으로 제한됩니다. build_timeout_in_minutes 속성을 설정하여 빌드 시간 제한을 연장할 수 있습니다.
...
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: 'upload'
app_location: 'src'
api_location: 'api'
output_location: 'public'
build_timeout_in_minutes: 30
배포 비밀 없이 워크플로 실행
일부 비밀이 누락된 경우에도 계속 처리하려면 워크플로가 필요한 경우가 있습니다. 정의된 비밀 없이 진행하도록 워크플로를 구성하려면 SKIP_DEPLOY_ON_MISSING_SECRETS 환경 변수를 true로 설정합니다.
이 기능을 사용하도록 설정하면 사이트 콘텐츠를 배포하지 않고도 워크플로를 계속할 수 있습니다.
...
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: 'upload'
app_location: 'src'
api_location: 'api'
output_location: 'public'
env:
SKIP_DEPLOY_ON_MISSING_SECRETS: true
환경 변수
작업 구성의 env 섹션을 통해 빌드에 대한 환경 변수를 설정할 수 있습니다.
...
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: 'upload'
app_location: 'src'
api_location: 'api'
output_location: 'public'
env: # Add environment variables here
HUGO_VERSION: 0.58.0
monorepo 지원
monorepo는 둘 이상의 애플리케이션에 대한 코드를 포함하는 리포지토리입니다. 기본적으로 Static Web Apps 워크플로 파일은 리포지토리의 모든 파일을 추적하지만 단일 앱을 대상으로 구성을 조정할 수 있습니다.
단일 앱의 대상으로 워크플로 파일을 지정하려면 push 및 pull_request 섹션에 경로를 지정합니다.
단일 리포지토리를 설정할 때 각 정적 앱 구성은 단일 앱의 파일로만 범위가 한정됩니다. 다른 워크플로 파일은 리포지토리의 .github/workflows 폴더에 나란히 표시됩니다.
├── .github
│ └── workflows
│ ├── azure-static-web-apps-purple-pond.yml
│ └── azure-static-web-apps-yellow-shoe.yml
│
├── app1 👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2 👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1 👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2 👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md
다음 예에서는 azure-static-web-apps-purple-pond.yml 파일의 push 및 pull_request 섹션에 paths 노드를 추가하는 방법을 보여 줍니다.
on:
push:
branches:
- main
paths:
- app1/**
- api1/**
- .github/workflows/azure-static-web-apps-purple-pond.yml
pull_request:
types: [opened, synchronize, reopened, closed]
branches:
- main
paths:
- app1/**
- api1/**
- .github/workflows/azure-static-web-apps-purple-pond.yml
이 예제에서 다음 파일에 대한 변경 내용만 새 빌드를 트리거합니다.
- app1 폴더 내의 모든 파일
- api1 폴더 내의 모든 파일
- 앱의 azure-static-web-apps-purple-pond.yml 워크플로 파일에 대한 변경 내용