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 폴더에 저장됩니다.

기본적으로 구성 파일은 이름이 azure-pipelines.yml인 리포지토리의 루트에 저장됩니다.

보안

두 가지 배포 권한 부여 정책 중에서 선택하여 빌드 구성을 보호할 수 있습니다. Static Web Apps는 Azure 배포 토큰(권장) 또는 GitHub 액세스 토큰을 사용하도록 지원합니다.

다음 단계를 사용하여 앱에서 배포 권한 부여 정책을 설정합니다.

• 새 앱: 정적 웹앱을 만들 때 배포 구성 탭에서 배포 권한 부여 정책을 선택합니다.

• 기존 앱: 기존 앱을 업데이트하려면 설정>구성>배포 구성으로 이동하여 배포 권한 부여 정책을 선택합니다.

빌드 구성

다음 샘플 구성은 리포지토리의 변경 내용을 모니터링합니다. 커밋이 main 분기에 푸시되면 애플리케이션이 app_location 폴더에서 빌드되고 output_location의 파일이 공용 웹에 제공됩니다. 또한 api 폴더의 애플리케이션은 사이트의 api 경로에서 사용할 수 있습니다.

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'src' # App source code path relative to cwd
      api_location: 'api' # Api source code path relative to cwd
      output_location: 'public' # Built app content directory relative to app_location - optional
      cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
      azure_static_web_apps_api_token: $(deployment_token)

이 구성에서:

• main 분기는 커밋에 대해 모니터링됩니다.
• app_location은 웹앱의 원본 파일이 포함된 src 폴더를 가리킵니다. 이 값은 작업 디렉터리(cwd)와 관계가 있습니다. 작업 디렉터리로 설정하려면 /를 사용합니다.
• api_location은 사이트의 API 엔드포인트에 대한 Azure Functions 애플리케이션이 포함된 api 폴더를 가리킵니다. 이 값은 작업 디렉터리(cwd)와 관계가 있습니다. 작업 디렉터리로 설정하려면 /를 사용합니다.
• output_location은 앱의 원본 파일의 최종 버전을 포함하는 public 폴더를 가리킵니다. 이 값은 app_location과 관계가 있습니다. .NET 프로젝트의 경우 위치는 출력 폴더를 기준으로 합니다.
• cwd는 작업 디렉터리를 가리키는 절대 경로입니다. 기본값은 $(System.DefaultWorkingDirectory)입니다.
• $(deployment_token) 변수는 생성된 Azure DevOps 배포 토큰을 가리킵니다.

참고 항목

app_location 및 api_location은 작업 디렉터리(cwd)와 관계가 있으며 cwd 아래의 하위 디렉터리여야 합니다.

Azure 배포 토큰

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
      - dev
  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
    permissions:
       id-token: write
       contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - name: Install OIDC Client from Core Package
        run: npm install @actions/core@1.6.0 @actions/http-client
      - name: Get Id Token
        uses: actions/github-script@v6
        id: idtoken
        with:
           script: |
               const coredemo = require('@actions/core')
               return await coredemo.getIDToken()
           result-encoding: string
      - 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_GENTLE_WATER }}
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "dist/angular-basic" # Built app content directory - optional
          production_branch: "dev"
          github_id_token: ${{ steps.idtoken.outputs.result }}
          ###### 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_GENTLE_WATER_030D91C1E }}
          action: "close"

GitHub 액세스 토큰

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에서 설정되므로 변경하지 마세요.

끌어오기 요청 닫기 작업은 빌드 및 배포를 트리거한 끌어오기 요청을 자동으로 닫습니다. 이 선택적 작업은 프로세스가 작동하는 데 필요하지 않습니다.

끌어오기 요청이 열리면 Azure Static Web Apps GitHub 작업이 앱을 빌드하고 스테이징 환경에 배포합니다. 그런 다음 끌어오기 요청 닫기 작업은 끌어오기 요청이 아직 열려 있는지 확인하고 완료 메시지와 함께 닫힙니다.

이 작업은 끌어오기 요청 워크플로를 체계적으로 유지하고 부실한 끌어오기 요청을 방지하는 데 도움이 됩니다. 런타임이 끌어오기 요청을 자동으로 닫으면 리포지토리가 최신 상태로 유지되고 팀에 상태가 통보됩니다.

끌어오기 요청 닫기 작업은 Azure Static Web Apps GitHub Actions 워크플로의 일부로 병합된 후 끌어오기 요청을 닫습니다. Azure/static-web-apps-deploy 작업은 Azure Static Web Apps에 앱을 배포하며 인증을 위해 azure_static_web_apps_api_token이 필요합니다.

사용자 지정 빌드 명령

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'

...

inputs:
  app_location: 'src'
  api_location: 'api'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)

프런트 엔드 앱 빌드 건너뛰기

프런트 엔드 앱에 대한 빌드를 완전히 제어해야 하는 경우 자동 빌드를 무시하고 이전 단계에서 빌드된 앱을 배포할 수 있습니다.

프런트 엔드 앱 빌드를 건너뛰려면 다음을 수행합니다.

• 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

...

inputs:
  app_location: 'src/dist'
  api_location: 'api'
  output_location: '' # Leave this empty
  skip_app_build: true
  azure_static_web_apps_api_token: $(deployment_token)

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

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

빌드 시간 제한 연장

기본적으로 앱 및 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

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

배포 비밀 없이 워크플로 실행

일부 비밀이 누락된 경우에도 계속 처리하려면 워크플로가 필요한 경우가 있습니다. 정의된 비밀 없이 계속 진행하도록 워크플로를 구성하려면 환경 변수true를 SKIP_DEPLOY_ON_MISSING_SECRETS .로 설정합니다.

이 기능을 사용하도록 설정하면 사이트 콘텐츠를 배포하지 않고도 워크플로를 계속할 수 있습니다.

...

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

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

환경 변수

작업 구성의 env 섹션을 통해 빌드에 대한 환경 변수를 설정할 수 있습니다.

Oryx에서 사용하는 환경 변수에 대한 자세한 내용은 Oryx 구성을 참조하세요.

...

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

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
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 워크플로 파일에 대한 변경 내용

단일 리포지토리에서 둘 이상의 애플리케이션을 지원하려면 별도의 워크플로 파일을 만들고 다른 Azure Pipelines와 연결합니다.

다음 단계

사전 프로덕션 환경에서 끌어오기 요청 검토