Azure Static Web Apps için derleme yapılandırması

Makale
11/05/2024

Azure Static Web Apps derleme yapılandırması GitHub Actions veya Azure Pipelines kullanır. Her sitenin, sitenin nasıl derlendiğini ve dağıtıldığını denetlediği bir YAML yapılandırma dosyası vardır. Bu makalede dosyanın yapısı ve seçenekleri açıklanmaktadır.

Aşağıdaki tabloda kullanılabilir yapılandırma ayarları listelenir.

Özellik	Açıklama	Gerekli
`app_location`	Bu klasör ön uç uygulamanızın kaynak kodunu içerir. Değer GitHub'daki depo köküne ve Azure DevOps'taki geçerli çalışma klasörüne göredir. ile `skip_app_build: true`kullanıldığında, bu değer uygulamanın derleme çıkış konumudur.	Yes
`api_location`	API uygulamanızın kaynak kodunu içeren bu klasör. Değer GitHub'daki depo köküne ve Azure DevOps'taki geçerli çalışma klasörüne göredir. ile `skip_api_build: true`kullanıldığında, bu değer API'nin derleme çıkış konumudur.	Hayır
`output_location`	Web uygulamanız bir derleme adımı çalıştırıyorsa, çıkış konumu ortak dosyaların oluşturulduğu klasördür. Çoğu proje için , `output_location` ile `app_location`görelidir. Ancak, .NET projeleri için konum çıkış klasörüne göredir.	Hayır
`app_build_command`	Node.js uygulamalar için statik içerik uygulamasını derlemek için özel bir komut tanımlayabilirsiniz. Örneğin, Angular uygulaması için bir üretim derlemesi yapılandırmak için komutunu çalıştırmak `ng build --prod` ve özel komut olarak girmek `npm run build-prod` üzere adlı `build-prod` bir npm betiği oluşturun. Boş bırakılırsa, iş akışı veya `npm run build:azure` komutlarını çalıştırmayı `npm run build` dener.	Hayır
`api_build_command`	Node.js uygulamalar için, Azure İşlevleri API uygulamasını derlemek için özel bir komut tanımlayabilirsiniz.	Hayır
`skip_app_build`	Ön uç uygulamasını derlemeyi atlamak için değerini `true` olarak ayarlayın.	Hayır
`skip_api_build`	API işlevlerini derlemeyi atlamak için değerini `true` olarak ayarlayın.	Hayır
`cwd` (Yalnızca Azure Pipelines)	Çalışma klasörünün mutlak yolu. varsayılan değeridir `$(System.DefaultWorkingDirectory)`.	Hayır
`build_timeout_in_minutes`	Derleme zaman aşımını özelleştirmek için bu değeri ayarlayın. varsayılan değeridir `15`.	Hayır

Bu ayarlarla GitHub Actions'ı veya Azure Pipelines'ı statik web uygulamanız için sürekli tümleştirme/sürekli teslim (CI/CD) çalıştıracak şekilde ayarlayabilirsiniz.

Dosya adı ve konumu

GitHub eylemi yapılandırma dosyasını oluşturur ve şu biçim kullanılarak adlandırılan .github/workflows klasöründe depolanır: azure-static-web-apps-<RANDOM_NAME>.yml.

Varsayılan olarak, yapılandırma dosyası deponuzun kökünde adıyla azure-pipelines.ymldepolanır.

Güvenlik

Derleme yapılandırmanızın güvenliğini sağlamak için iki farklı dağıtım yetkilendirme ilkesi arasından seçim yapabilirsiniz. Statik Web Apps, Azure dağıtım belirteci (önerilen) veya GitHub erişim belirteci kullanmayı destekler.

Uygulamanızda dağıtım yetkilendirme ilkesini ayarlamak için aşağıdaki adımları kullanın:

Yeni uygulamalar: Statik web uygulamanızı oluşturduğunuzda, Dağıtım yapılandırması sekmesinde Dağıtım yetkilendirme ilkesi için bir seçim yapın.
Mevcut uygulamalar: Mevcut bir uygulamayı güncelleştirmek için Ayarlar>Yapılandırma>Dağıtımı yapılandırması'na gidin ve Dağıtım yetkilendirme ilkesi için bir seçim yapın.

Yapı yapılandırması

Aşağıdaki örnek yapılandırma, depoyu değişiklikler için izler. İşlemeler dala gönderildiğinde main , uygulama klasöründen app_location oluşturulur ve içindeki output_location dosyalar genel web'e sunulur. Buna ek olarak, api klasöründeki uygulama sitenin api yolunda kullanılabilir.

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)

Bu yapılandırmada:

Dal main işlemeler için izlenir.
Web app_location uygulamasının src kaynak dosyalarını içeren klasörü gösterir. Bu değer çalışma dizinine () göredircwd. Bunu çalışma dizinine ayarlamak için kullanın /.
Sitenin api_location api API uç noktaları için Azure İşlevleri uygulamasını içeren klasörü gösterir. Bu değer çalışma dizinine () göredircwd. Bunu çalışma dizinine ayarlamak için kullanın /.
Uygulamanın output_location kaynak dosyalarının public son sürümünü içeren klasörü gösterir. Bu değer ile app_locationgörelidir. .NET projeleri için konum çıkış klasörüne göredir.
cwd, çalışma dizinine işaret eden mutlak bir yoldur. Varsayılan olarak olur $(System.DefaultWorkingDirectory).
Değişken, $(deployment_token) oluşturulan Azure DevOps dağıtım belirtecini gösterir.

Not

app_location ve api_location çalışma dizinine (cwd) göre olmalı ve altında cwdalt dizinler olmalıdır.

Azure dağıtım belirteci
GitHub erişim belirteci

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"

Bu yapılandırmada:

Dal main işlemeler için izlenir.
Daldaki main bir çekme isteği açıldığında, eşitlendiğinde, yeniden açıldığında veya kapatıldığında GitHub Actions iş akışı tetiklenir.
yürütmeleri build_and_deploy_job gönderdiğinizde veya özelliğinde listelenen dalda bir çekme isteği açtığınızda yürütülür on .
Web app_location uygulamasının src kaynak dosyalarını içeren klasörü gösterir. Bu değeri depo köküne ayarlamak için kullanın /.
Sitenin api_location api API uç noktaları için Azure İşlevleri uygulamasını içeren klasörü gösterir. Bu değeri depo köküne ayarlamak için kullanın /.
Uygulamanın output_location kaynak dosyalarının public son sürümünü içeren klasörü gösterir. ile görelidir app_location. .NET projeleri için konum yayımlama çıktı klasörüne göredir.

Azure Static Web Apps tarafından sizin için repo_tokenayarlanmış olan , actionve azure_static_web_apps_api_token değerlerini değiştirmeyin.

Çekme İsteğini Kapat işi, derlemeyi ve dağıtımı tetikleyen çekme isteğini otomatik olarak kapatır. İşlemin çalışması için bu isteğe bağlı iş gerekli değildir.

Çekme isteği açıldığında, Azure Static Web Apps GitHub Action oluşturulur ve bir hazırlama ortamına dağıtılır. Daha sonra Çekme İsteğini Kapat işi, çekme isteğinin hala açık olup olmadığını denetler ve bir tamamlama iletisiyle kapatır.

Bu iş, çekme isteği iş akışınızın düzenli kalmasına yardımcı olur ve eski çekme isteklerini önler. Çalışma zamanı çekme isteğini otomatik olarak kapatarak deponuz güncel kalır ve ekibinize durum bildirilir.

Çekme İsteğini Kapat işi, Azure Static Web Apps GitHub Actions iş akışının bir parçasıdır ve çekme isteği birleştirildikten sonra kapatılır. Eylem, Azure/static-web-apps-deploy uygulamayı Azure Static Web Apps'e dağıtır ve azure_static_web_apps_api_token kimlik doğrulaması gerekir.

Özel derleme komutları

Node.js uygulamalar için uygulama veya API derleme işlemi sırasında çalıştırılan komutlar üzerinde ayrıntılı denetime sahip olabilirsiniz. Aşağıdaki örnekte ve api_build_commanddeğerleriyle derlemenin nasıl tanımlanacağı gösterilmektedirapp_build_command.

Not

Şu anda yalnızca Node.js derlemeler için ve api_build_command tanımlayabilirsinizapp_build_command. Node.js sürümünü belirtmek için dosyadaki package.json alanını kullanınengines.

...

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)

Ön uç uygulaması derlemeyi atlama

Ön uç uygulamanız için derlemenin tam denetimine ihtiyacınız varsa, otomatik derlemeyi atlayabilir ve önceki adımda oluşturulan uygulamayı dağıtabilirsiniz.

Ön uç uygulamasını derlemeyi atlamak için:

Dağıtmak istediğiniz dosyaların konumuna ayarlayın app_location .
skip_app_build seçeneğini true olarak ayarlayın.
Boş bir dizeye ()'' ayarlayınoutput_location.

Not

Dosyanızın staticwebapp.config.json da çıkış dizinine kopyaladığınızdan emin olun.

...

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'yi derlemeyi atlama

API'yi derlemeyi atlamak istiyorsanız, otomatik derlemeyi atlayabilir ve önceki adımda oluşturulan API'yi dağıtabilirsiniz.

API'yi derlemeyi atlama adımları:

staticwebapp.config.json dosyasında doğru çalışma zamanına ve sürüme ayarlayınapiRuntime. Desteklenen çalışma zamanlarının ve sürümlerin listesi için Bkz. Azure Static Web Apps'i yapılandırma.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
skip_api_build seçeneğini true olarak ayarlayın.
Dağıtılacak yerleşik API uygulamasını içeren klasöre ayarlayın api_location . Bu yol GitHub Actions ve cwd Azure Pipelines'daki depo köküne göredir.

...

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)

Derleme zaman aşımını genişletme

Varsayılan olarak, uygulama ve API derlemeleri 15 dakika ile sınırlıdır. Özelliğini ayarlayarak derleme zaman aşımını build_timeout_in_minutes genişletebilirsiniz.

...

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)

Dağıtım gizli dizileri olmadan iş akışı çalıştırma

Bazen bazı gizli diziler eksik olsa bile iş akışınızın işlemeye devam etmesi gerekir. İş akışınızı tanımlı gizli diziler olmadan devam etmek üzere yapılandırmak için ortam değişkenini SKIP_DEPLOY_ON_MISSING_SECRETS olarak trueayarlayın.

Bu özellik etkinleştirildiğinde, iş akışının sitenin içeriğini dağıtmadan devam etmesini sağlar.

...

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

Ortam değişkenleri

Derlemeniz için ortam değişkenlerini bir işin yapılandırmasının bölümü aracılığıyla env ayarlayabilirsiniz.

Oryx tarafından kullanılan ortam değişkenleri hakkında daha fazla bilgi için bkz . Oryx yapılandırması.

...

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 desteği

Monorepo, birden fazla uygulamanın kodunu içeren bir depodur. varsayılan olarak, iş akışı bir depodaki tüm dosyaları izler, ancak yapılandırmayı tek bir uygulamayı hedeflemek için ayarlayabilirsiniz.

bir iş akışı dosyasını tek bir uygulamaya hedeflemek için ve pull_request bölümlerinde yolları push belirtirsiniz.

Monorepo ayarladığınızda, her statik uygulama yapılandırmasının kapsamı yalnızca tek bir uygulama için dosya olarak belirlenmiştir. Farklı iş akışı dosyaları, deponun .github/workflows klasöründe yan yana bulunur.

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

Aşağıdaki örnekte, azure-static-web-apps-purple-pond.yml adlı dosyanın ve pull_request bölümlerine push nasıl düğüm ekleneceği paths gösterilmektedir.

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

Bu örnekte, yalnızca aşağıdaki dosyalarda yapılan değişiklikler yeni bir derlemeyi tetikler:

app1 klasörünün içindeki tüm dosyalar
api1 klasörünün içindeki tüm dosyalar
Uygulamanın azure-static-web-apps-purple-pond.yml iş akışı dosyasında yapılan değişiklikler

Tek bir depoda birden fazla uygulamayı desteklemek için ayrı bir iş akışı dosyası oluşturun ve bunu farklı Azure Pipelines ile ilişkilendirin.

Sonraki adımlar

Üretim öncesi ortamlarda çekme isteklerini gözden geçirme

Aracılığıyla paylaş