Simplifying Retype Deployments with Azure Static Web Apps

[JoelMTaylor]

Show and Tell: Simplifying Retype Deployments with Azure Static Web Apps

Introduction

Deploying static websites with Retype and Azure Static Web Apps (SWA) can be incredibly streamlined, but the process isn't without its challenges. This post documents the journey of replacing an inefficient two-step GitHub Actions workflow with a single streamlined solution, while tackling branch management, GitHub token limitations, and general workflow design.

Technologies Used

• Retype for generating static sites from Markdown.
• Azure Static Web Apps for hosting the static content.

---

Original Two-Step Workflow

Overview

Initially, the workflow required two separate GitHub Actions inside one yml file:

1. Action 1: Generate the static site in the wwwroot folder of the main branch.
2. Action 2: Publish the contents of the wwwroot folder to Azure Static Web Apps.

Problem

The two-step approach required two pushes to update the live site:

1. The first push updated the wwwroot folder in main.
2. A second push triggered the Azure workflow to deploy the updated static site.

This redundancy was time-consuming and error-prone, prompting a search for a better solution.

---

Transitioning to a Single-Step Workflow

New Approach

The goal was to directly publish the static content generated by Retype into a publish branch (same/equivalent to the default retype branch), separate from main, and trigger the Azure deployment from this branch.

Using Retype's default example GitHub Action (example here) and the automatically generated Azure SWA action as templates, the following issues arose:

Challenges Encountered

1. Branch Management Confusion

GitHub typically treats branch workflows as duplications, whereas Retype expects the publish (retype) branch to host entirely different static content. Understanding this distinction was key to aligning the workflows. It is worth noting that during this process, the "1 commit behind/ahead" status on the publish branch can generally be ignored without impacting functionality.

2. GitHub Token Limitation

By default, GitHub prevents workflows from triggering subsequent workflows if changes are pushed using the default GITHUB_TOKEN. As stated in GitHub Community Discussions (also, see this other related discussion here):

"If an action pushes code using the repository’s GITHUB_TOKEN, a new workflow will not run even when the repository contains a workflow configured to run when push events occur."

This limitation required the use of a Personal Access Token (PAT) with appropriate permissions.

---

Final Solution

Here are the final GitHub Actions workflows that resolved the issues.

retype-build.yml

name: Build and Push Website to Publish Branch

on:
  workflow_dispatch:
  push:
    branches:
      - main  # Trigger on changes to the main branch

jobs:
  build:
    name: Build and Deploy to Publish Branch
    runs-on: ubuntu-latest

    permissions:
      contents: write  # Required to push changes to the `publish` branch

    steps:
      # Step 1: Check out the main branch
      - name: Checkout Main Branch
        uses: actions/checkout@v4
        with:
          ref: main  # Explicitly check out the main branch
          persist-credentials: false  # Ensures the PAT is used later

      # Step 2: Set up .NET for Retype
      - name: Setup .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 7.0.x

      # Step 3: Build the website using Retype
      - name: Build Website
        uses: retypeapp/action-build@latest
        with:
          license: ${{ secrets.RETYPE_SECRET }}

      # Step 4: Set up Git with PAT
      - name: Set Up Git with PAT
        env:
          PAT: ${{ secrets.PAT_PUSH_TO_PUBLISH_BRANCH }}
        run: |
          git config user.name "GitHub Actions"
          git config user.email "[email protected]"
          git remote set-url origin https://[email protected]/${{ github.repository }}

      # Step 5: Deploy built website to the `publish` branch
      - name: Deploy to Publish Branch
        uses: retypeapp/action-github-pages@latest
        with:
          branch: publish  # Specify `publish` as the target branch instead of the default `retype`
          update-branch: true

azure-publish.yml

name: Deploy to Azure Static Web Apps

on:
  push:
    branches:
      - publish  # Trigger on changes to the publish branch
  workflow_dispatch: # Allow manual runs

jobs:
  deploy:
    name: Deploy to Azure Static Web Apps
    runs-on: ubuntu-latest

    steps:
      # Step 1: Check out the publish branch
      - name: Checkout Publish Branch
        uses: actions/checkout@v3

      # Step 2: Deploy to Azure
      - name: Deploy to Azure Static Web Apps
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_SECRET }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: "upload"
          app_location: "/" # Root directory contains the built content
          api_location: "" # No API
          output_location: "" # No additional build step

---

Key Learnings

1. Understand Workflow Behavior:

   • GitHub’s branch duplication behavior differs from Retype’s expectation of a clean branch for hosting static content. This required explicitly setting up the publish branch logic.

2. PAT Usage is Essential:

   • The default GITHUB_TOKEN cannot trigger subsequent workflows. Using a PAT resolved this issue and enabled seamless integration between Retype and Azure SWA.

3. Efficient Builds Save Time:

   • By simplifying the workflow and leveraging Retype’s build capabilities directly, the process became significantly faster (45 seconds vs. 2–3 minutes previously).

---

Links and Resources

• Azure Static Web Apps Documentation
• Retype GitHub Actions Guide
• GitHub Community Discussion: Pushing a Tag Doesn’t Trigger Another Workflow
• GitHub Community Discussion: Workflow Dependencies

---

Conclusion

This experience highlighted the importance of understanding GitHub workflows, branch management, and the nuances of authentication tokens. By combining Retype and Azure Static Web Apps with thoughtful GitHub Actions workflows, we achieved a streamlined deployment process.

Feel free to share your own tips or similar experiences in the comments below!