Bangun konfigurasi untuk Azure Static Web Apps

Artikel
11/05/2024

Konfigurasi build Azure Static Web Apps menggunakan GitHub Actions atau Azure Pipelines. Setiap situs memiliki file konfigurasi YAML yang mengontrol bagaimana sebuah situs dibangun dan digunakan. Artikel ini menjelaskan struktur dan opsi file.

Tabel berikut mencantumkan pengaturan konfigurasi yang tersedia.

Properti	Deskripsi	Wajib diisi
`app_location`	Folder ini berisi kode sumber untuk aplikasi front-end Anda. Nilai ini relatif terhadap root repositori di GitHub dan folder kerja saat ini di Azure DevOps. Saat digunakan dengan `skip_app_build: true`, nilai ini adalah lokasi output build aplikasi.	Ya
`api_location`	Folder ini yang berisi kode sumber untuk aplikasi API Anda. Nilai ini relatif terhadap root repositori di GitHub dan folder kerja saat ini di Azure DevOps. Saat digunakan dengan `skip_api_build: true`, nilai ini adalah lokasi output build API.	No
`output_location`	Jika aplikasi web Anda menjalankan langkah build, lokasi output adalah folder tempat file publik dihasilkan. Untuk sebagian besar proyek, `output_location` relatif terhadap `app_location`. Namun, untuk proyek .NET, lokasi relatif terhadap folder output.	No
`app_build_command`	Untuk aplikasi Node.js, Anda dapat menentukan perintah khusus untuk membangun aplikasi konten statis. Misalnya, untuk mengonfigurasi build produksi untuk aplikasi Angular, buat skrip npm bernama `build-prod` untuk menjalankan`ng build --prod` dan masukkan `npm run build-prod` sebagai perintah kustom. Jika dibiarkan kosong, alur kerja mencoba menjalankan perintah `npm run build` atau `npm run build:azure`.	No
`api_build_command`	Untuk aplikasi Node.js, Anda dapat menentukan perintah kustom untuk membangun aplikasi Azure Functions API.	No
`skip_app_build`	Atur nilai ke `true` untuk melewati pembuatan aplikasi front-end.	No
`skip_api_build`	Atur nilai ke `true` untuk melewati pembuatan fungsi API.	No
`cwd` (Hanya Azure Pipelines)	Jalur absolut ke folder kerja. Default ke `$(System.DefaultWorkingDirectory)`.	No
`build_timeout_in_minutes`	Atur nilai ini untuk menyesuaikan batas waktu build. Default ke `15`.	No

Dengan pengaturan ini, Anda dapat mengatur GitHub Actions atau Azure Pipelines untuk menjalankan continuous integration/continuous delivery (CI/CD) untuk aplikasi web statis Anda.

Nama dan lokasi file

Tindakan GitHub menghasilkan file konfigurasi dan disimpan di folder .github/workflows , bernama menggunakan format berikut: azure-static-web-apps-<RANDOM_NAME>.yml.

Secara default, file konfigurasi disimpan di akar repositori Anda dengan nama azure-pipelines.yml.

Keamanan

Anda dapat memilih antara dua kebijakan otorisasi penyebaran yang berbeda untuk mengamankan konfigurasi build Anda. Static Web Apps mendukung penggunaan token penyebaran Azure (disarankan), atau token akses GitHub.

Gunakan langkah-langkah berikut untuk mengatur kebijakan otorisasi penyebaran di aplikasi Anda:

Aplikasi baru: Saat Anda membuat aplikasi web statis, pada tab Konfigurasi penyebaran, buat pilihan untuk kebijakan otorisasi Penyebaran.
Aplikasi yang ada: Untuk memperbarui aplikasi yang ada, buka Konfigurasi Penyebaran Konfigurasi>Pengaturan>, dan buat pilihan untuk kebijakan otorisasi Penyebaran.

Konfigurasi build

Konfigurasi sampel berikut memantau repositori untuk perubahan. Saat commits didorong ke main cabang, aplikasi ini dibangun dari app_location folder dan file di dilayani ke web output_location publik. Selain itu, aplikasi dalam folder api tersedia di bawah api jalur situs.

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)

Dalam konfigurasi ini:

Bagian main dipantau untuk berkomitmen.
Titik app_location ke src folder yang berisi file sumber untuk aplikasi web. Nilai ini relatif terhadap direktori kerja (cwd). Untuk mengaturnya ke direktori kerja, gunakan /.
Titik-titik api_location ke folder api yang berisi aplikasi Azure Functions untuk titik akhir API situs. Nilai ini relatif terhadap direktori kerja (cwd). Untuk mengaturnya ke direktori kerja, gunakan /.
Titik output_location ke folder public yang berisi versi final file sumber aplikasi. Nilai ini relatif terhadap app_location. Untuk proyek .NET, lokasi relatif terhadap folder output.
cwd adalah jalur absolut yang menunjuk ke direktori kerja. Ini default ke $(System.DefaultWorkingDirectory).
Variabel $(deployment_token) menunjuk ke token penyebaran Azure DevOps yang dihasilkan.

Catatan

app_location dan api_location harus relatif terhadap direktori kerja (cwd) dan harus subdirektori di bawah cwd.

Token penyebaran Azure
Token akses GitHub

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"

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"

Dalam konfigurasi ini:

Bagian main dipantau untuk berkomitmen.
Alur kerja tindakan GitHub dipicu saat permintaan tarik pada bagian main adalah: dibuka, disinkronkan, dibuka kembali, atau ditutup.
build_and_deploy_job mengeksekusi saat Anda mendorong penerapan atau membuka permintaan pull terhadap cabang yang tercantum di properti on.
Titik app_location ke src folder yang berisi file sumber untuk aplikasi web. Untuk mengatur nilai ini ke akar repositori, gunakan /.
Titik-titik api_location ke folder api yang berisi aplikasi Azure Functions untuk titik akhir API situs. Untuk mengatur nilai ini ke akar repositori, gunakan /.
Titik output_location ke folder public yang berisi versi final file sumber aplikasi. Ini relatif terhadap app_location. Untuk proyek .NET, lokasi relatif terhadap folder terbitkan output.

Jangan ubah nilai untuk repo_token, action, dan azure_static_web_apps_api_token karena nilai itu ditetapkan untuk Anda oleh Azure Static Web Apps.

Pekerjaan Tutup Permintaan Pull secara otomatis menutup permintaan pull yang memicu build dan penyebaran. Pekerjaan opsional ini tidak diperlukan agar proses berfungsi.

Saat permintaan pull dibuka, Azure Static Web Apps GitHub Action membangun dan menyebarkan aplikasi ke lingkungan penahapan. Setelah itu, pekerjaan Tutup Permintaan Pull memeriksa apakah permintaan pull masih terbuka dan menutupnya dengan pesan penyelesaian.

Pekerjaan ini membantu menjaga alur kerja permintaan pull Anda tetap terorganisir dan mencegah permintaan pull kedaluarsa. Dengan runtime secara otomatis menutup permintaan pull, repositori Anda tetap terbarui dan tim Anda diberi tahu tentang status tersebut.

Pekerjaan Tutup Permintaan Pull adalah bagian dari alur kerja GitHub Actions Azure Static Web Apps, menutup permintaan pull setelah digabungkan. Tindakan ini Azure/static-web-apps-deploy menyebarkan aplikasi ke Azure Static Web Apps, yang azure_static_web_apps_api_token memerlukan untuk autentikasi.

Perintah build kustom

Untuk aplikasi Node.js, Anda dapat mengambil kontrol halus atas perintah apa yang dijalankan selama proses pembuatan aplikasi atau API. Contoh berikut menunjukkan cara mendefinisikan build dengan nilai untuk app_build_command dan api_build_command.

Catatan

Saat ini, Anda hanya dapat mendefinisikan app_build_command dan api_build_command untuk build Node.js. Untuk menentukan versi Node.js, gunakan engines bidang dalam package.json file.

...

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)

Lompati membangun aplikasi front-end

Jika Anda memerlukan kontrol penuh atas build untuk aplikasi front-end Anda, Anda dapat melewati build otomatis dan menerapkan aplikasi yang dibangun pada langkah sebelumnya.

Untuk melewatkan membangun aplikasi front-end:

Atur app_location ke lokasi file yang ingin Anda terapkan.
Atur skip_app_build ke true.
Atur output_location ke string kosong ('').

Catatan

Pastikan file Anda staticwebapp.config.json juga disalin ke direktori output .

...

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)

Lewati pembuatan API

Jika Anda ingin melewati pembangunan API, Anda dapat melewati build otomatis dan menyebarkan API yang dibangun pada langkah sebelumnya.

Langkah-langkah untuk melewati pembuatan API:

Dalam file staticwebapp.config.json, atur apiRuntime ke runtime dan versi yang benar. Lihat Mengonfigurasi Azure Static Web Apps untuk daftar runtime dan versi yang didukung.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
Atur skip_api_build ke true.
Atur api_location ke folder yang berisi aplikasi API bawaan untuk disebarkan. Jalur ini relatif terhadap akar repositori di GitHub Actions dan cwd di Azure Pipelines.

...

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)

Memperpanjang batas waktu build

Secara default, build aplikasi dan API dibatasi hingga 15 menit. Anda dapat memperpanjang batas waktu build dengan mengatur build_timeout_in_minutes properti .

...

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)

Jalankan alur kerja tanpa rahasia penyebaran

Terkadang Anda memerlukan alur kerja Anda untuk terus memproses bahkan ketika beberapa rahasia hilang. Untuk mengonfigurasi alur kerja Anda untuk melanjutkan tanpa rahasia yang ditentukan, atur SKIP_DEPLOY_ON_MISSING_SECRETS variabel lingkungan ke true.

Saat diaktifkan, fitur ini memungkinkan alur kerja untuk melanjutkan tanpa menyebarkan konten situs.

...

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

Variabel lingkungan

Anda dapat mengatur variabel lingkungan untuk build melalui bagian env konfigurasi pekerjaan.

Untuk informasi selengkapnya tentang variabel lingkungan yang digunakan oleh Oryx, lihat Konfigurasi 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

Dukungan Monorepo

Monorepo adalah repositori yang berisi kode untuk lebih dari satu aplikasi. Secara default, alur kerja melacak semua file dalam repositori, tetapi Anda dapat menyesuaikan konfigurasi untuk menargetkan satu aplikasi.

Untuk menargetkan file alur kerja ke satu aplikasi, Anda menentukan jalur di bagian push dan pull_request.

Saat Anda menyiapkan monorepo, setiap konfigurasi aplikasi statis dicakup hanya untuk file untuk satu aplikasi. File alur kerja yang berbeda tinggal berdampingan di folder .github/workflows repositori.

├── .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

Contoh berikut menunjukkan cara menambahkan simpul paths ke bagian push dan pull_request file bernama azure-static-web-apps-purple-pond.yml.

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

Dalam contoh ini, hanya perubahan yang dilakukan pada file berikut yang memicu build baru:

File apa pun di dalam folder app1
File apa pun di dalam folder api1
Perubahan pada file alur kerja azure-static-web-apps-purple-pond.yml aplikasi

Untuk mendukung lebih dari satu aplikasi dalam satu repositori, buat file alur kerja terpisah dan kaitkan dengan Pipa Azure yang berbeda.

Langkah berikutnya

Meninjau permintaan pull di lingkungan pra-produksi

Bagikan melalui

Bangun konfigurasi untuk Azure Static Web Apps

Nama dan lokasi file

Keamanan

Konfigurasi build

Perintah build kustom

Lompati membangun aplikasi front-end

Lewati pembuatan API

Memperpanjang batas waktu build

Jalankan alur kerja tanpa rahasia penyebaran

Variabel lingkungan

Dukungan Monorepo

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: