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

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: truekullanı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: truekullanı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_locationgö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 build-prod ve özel komut olarak girmek ng build --prod üzere adlı npm run build-prod bir npm betiği oluşturun. Boş bırakılırsa, iş akışı veya npm run build komutlarını çalıştırmayı npm run build:azure 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 AyarlarYapılandırma>> 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_locationapi 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.

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"

Bu yapılandırmada:

  • Dal main işlemeler için izlenir.
  • Daldaki bir çekme isteği açıldığında, eşitlendiğinde, yeniden açıldığında veya kapatıldığında GitHub Actions iş akışı main.
  • 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_locationapi 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 app_build_commanddeğerleriyle derlemenin nasıl tanımlanacağı gösterilmektedirapi_build_command.

Not

Şu anda yalnızca Node.js derlemeler için ve app_build_command tanımlayabilirsinizapi_build_command. Node.js sürümünü belirtmek için dosyadaki engines alanını kullanınpackage.json.

...

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 ()output_location ayarlayın''.

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ı:

...

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 push bölümlerinde yolları pull_request 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 paths bölümlerine push nasıl düğüm ekleneceği pull_request 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

  • Last updated on