Deploying Docusaurus

Links

Link	Description
GitHub Action - Azure/static-web-apps-deploy@v1	The Azure Static Web Apps build configuration either uses GitHub Actions or Azure Pipelines. Each site has a YAML configuration file that controls how a site is built and deployed. This article explains the file's structure and options.
Configure a federated identity credential on an app	To set up a federated identity credential, you need to add a trust relationship between Azure Active Directory (Azure AD) and the identity provider (IdP) of your choice.

Setup Github Project

• Go to Github and create a new project.
• Give a repository name.
• Give a description.
• Select the visibility of the repository.
• Create the repository.

On your development machine, navigate to the root of your Docusaurus project and run the following commands:

Initalizing Git and Pushing to GitHub

echo "# Digital Reflections" >> README.md
git init
git add README.md
git commit -m "initial commit"
git branch -M main
git remote add origin https://github.com/cdly450/digital-reflections.git
git push -u origin main

On the git push command, you will be prompted for your Github username and password. Sign in with your Github credentials.

Using GitHub Actions Workflow

To use a GitHub Actions workflow to publish the site use the following steps. Below is a visual representation of the logical steps that the GitHub Workflow follows.

Install the Github Actions VSCode Extension

The GitHub Actions extension lets you manage your workflows, view the workflow run history, and helps with authoring workflows.

tip

More information can be found here: - GitHub Actions VSCode Extension

Install the GitHub CLI tool

Follow the instructions here to setup the CLI tool - GitHub CLI.

Setup GitHub Secrets

Configure secrets by using GitHub CLI. An example of how to do that can be found here - Setup GitHub Secrets

Setup GitHub SWA Token

When using Bicep to deploy the Static Web App, as part of the provisioning process, an Azure Static Web App Deployment Token is generated. That Azure Static Web App Deployment Token is then used by the GitHub Action workflow to publish the Docusaurus static website to the Static Web App.

In order for the Static Web App to be published to from the GitHub Action Workflow, the Azure Static Web App Deployment Token must be added to GitHub as a secret. To do this, follow the steps below.

• In the Bicep file, we specify the following parameters: -

param staticSiteObject = {
  sku: 'Free'
  name: 'digital-reflections'
  branch: 'main'
  repositoryUrl: 'https://github.com/cdly450/digital-reflections'
  repositoryToken: readEnvironmentVariable('GH_SWA_TOKEN')
  provider: 'GitHub'
  buildProperties: {
    appLocation: '/'
    appArtifactLocation: '/build'
    outputLocation: '/build'
    appBuildCommand: 'npm install && npm run build'
    skipGithubActionWorkflowGeneration: true
    githubActionSecretNameOverride: 'AZURE_STATIC_WEB_APPS_API_TOKEN'
  }
}

Parameter	Description
Branch	This is the branch that will be used to publish the static website to the Static Web App.
Repository URL	This is the URL of the GitHub repository that contains the source code for the static website.
Repository Token	This is the GitHub Personal Access Token that will be used by the Azure Static Web app to authenticate to GitHub. This token is used to create a GitHub Actions Workflow file and also to set a secret in the repository containing the Azure Static Web App Deployment Token. This allows the subsequent step in the GitHub Action Workflow to publish the static website to the Static Web App.
Provider	This is the source control provider that will be used to publish the static website to the Static Web App. In this case, we are using GitHub.
buildProperties.appLocation	This is the location of the source code for the static website. In this case, the source code is located at the root of the repository.
buildProperties.outputLocation	This is the location of the build output for the static website. In this case, the build output is located in the build directory.

Create a GitHub Actions Workflow File

• In the source code, create a .github/workflows directory in the root of the project.
• Create a new file named deploy.yml.

.github/workflows/deploy.yml

name: Azure Static Web App Build & Deploy CI/CD Pipeline

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install dependencies
        run: npm install

      - name: Build project
        run: npm run build
        env:
          GIT_USER: ${{ secrets.GH_NAME }}

      - name: Azure login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
          enable-AzPSSession: true
          auth-type: SERVICE_PRINCIPAL

      - name: Validate Bicep Template
        uses: azure/powershell@v2
        with:
          inlineScript: |
            $Inputs = @{
                Location = 'Australia East'
                TemplateParameterFile = "${{ github.workspace }}/infra/parameters/main.bicepparam"
            }
            Write-Verbose "Invoke Test-AzDeployment with `n$($Inputs | ConvertTo-Json | Out-String)" -Verbose
            Test-AzSubscriptionDeployment @Inputs -Verbose
          azPSVersion: "latest"

      - name: Deploy Bicep Template
        uses: azure/powershell@v2
        with:
          inlineScript: |
            $Inputs = @{
                Location = 'Australia East'
                TemplateParameterFile = "${{ github.workspace }}/infra/parameters/main.bicepparam"
            }
            Write-Verbose "Invoke New-AzDeployment with `n$($Inputs | ConvertTo-Json | Out-String)" -Verbose
            New-AzSubscriptionDeployment @Inputs -Verbose
          azPSVersion: "latest"

      - name: Deploy to Azure Static Web App
        uses: Azure/static-web-apps-deploy@v1
        with:
          app_location: "/build"
          skip_app_build: true
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: upload

Authenticating to Azure from GitHub Action

I was receiving the following error: -

Error: AADSTS70025: Client application has no configured federated identity credentials. Trace ID: abd45620-48ea-4c06-a7bd-302e98302e00 Correlation ID: 69480649-389a-4eaf-b6a1-468cb9e3a82b Timestamp: 2024-09-24 05:24:47Z

I needed to setup a federated identity credential for the service principal as documented here: - Configure a federated identity credential on an app.

Using Azure Pipelines

To use Azure Devops Pipelines to publish the static site use the following steps.

• Create a new project in Azure Devops and sign in.

• Navigate to the project and select Pipelines.

• Click on Create Pipeline.

• When it asks Where is your code?, select GitHub.
  

• Click on Authorize and sign in with your Github credentials.

• Select the repository you created earlier.
  

• Select Starter pipeline.

• Input the following yaml: -

  trigger:
    - main
  
  pool:
    vmImage: ubuntu-latest
  
  steps:
    - checkout: self
      persistCredentials: true
  
    - task: NodeTool@0
      inputs:
        versionSpec: "18"
      displayName: Install Node.js
  
    - script: |
        git config --global user.name "${GH_NAME}"
        git config --global user.email "${GH_EMAIL}"
        git checkout -b main
        echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
        npm install
        GIT_USER="${GH_NAME}" npm run build
      env:
        GH_NAME: $(GH_NAME)
        GH_EMAIL: $(GH_EMAIL)
        GH_TOKEN: $(GH_TOKEN)
      displayName: Install and build

  In the Variables section of your pipeline, set the ${GH_NAME}, ${GH_EMAIL} & ${GH_TOKEN}.

  Grab the token from Github for the token.

  Beautiful.