Add Azure Static Web Apps deployment with Bicep IaC and automated CI/CD

[Copilot]

Implements streamlined Azure Static Web Apps deployment to enable easy forking and self-hosting of the DocFX wiki.

Infrastructure as Code

Bicep Templates (infra/)

• main.bicep: Static Web App resource with parameterized SKU, location, tags
• bicep.parameters.json: Single customization point for deployment
• Outputs deployment token and site URL for automation

Deployment Script (deploy-azure.sh)

• One-command deployment: validates prerequisites, creates resource group, deploys Bicep, retrieves token
• Color-coded output with next steps

CI/CD Pipeline

GitHub Actions (.github/workflows/azure-swa-deploy.yml)

• Triggers: docs/** changes on main, PR events, manual dispatch
• Builds DocFX → deploys to Azure SWA
• PR preview environments with automatic cleanup
• Uses Azure/static-web-apps-deploy@v1 with pre-built output (skip_app_build: true)

Configuration

Runtime Config (staticwebapp.config.json)

• Navigation fallback for client-side routing
• Cache headers and MIME types
• 404 handling

Exclusions (.gitignore)

• Azure artifacts (.azure/, swa-cli.config.json)
• Bicep build outputs (keeps only bicep.parameters.json)

Documentation

• DEPLOYMENT.md: Step-by-step deployment guide with troubleshooting
• infra/README.md: Infrastructure-specific instructions
• README.md: Quick-start section for Azure SWA deployment option

Usage

# 1. Customize
nano infra/bicep.parameters.json  # Change staticWebAppName

# 2. Deploy
./deploy-azure.sh

# 3. Add GitHub secret
# AZURE_STATIC_WEB_APPS_API_TOKEN = [deployment token from step 2]

# 4. Push docs changes → automatic deployment

Maintains existing GitHub Pages deployment as alternative option.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• aka.ms
  • Triggering command: /usr/local/bin/bicep bicep build main.bicep (dns block)
  • Triggering command: /usr/local/bin/bicep bicep build main.bicep --stdout (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Start implementation

The user has attached the following file paths as relevant context:

• .github/copilot-instructions.md
• docs/index.md
• README.md
• docs/content/toc.yml
• docs/docfx.json
• LICENSE

[Chronological Review: The conversation began with the user discussing the deployment of a wiki to Azure Static Web Apps (SWA). The user expressed a desire for a streamlined process that allows others to clone the repository, modify parameters, and deploy the SWA using Bicep. The user also mentioned the need for a CI/CD workflow that triggers on updates to the documentation folder. The most recent interaction involved the user executing the 'semantic_search' tool to explore deployment options.]

[Intent Mapping: The user explicitly requested guidance on deploying the wiki to Azure SWA, stating, "I think doing continuous updates are easy enough... but I kind of would like to package up this repo as an easy-to-hand out scenario to people." They outlined a process involving cloning the repo, editing a Bicep parameter file, adding secrets for Azure authentication, and running a deployment command.]

[Technical Inventory: The conversation referenced Azure Static Web Apps, Bicep for infrastructure as code, and GitHub Actions for CI/CD workflows. The user also mentioned the existing GitHub workflow for deploying documentation to GitHub Pages.]

[Code Archaeology: The user attached the GitHub workflow file 'publish-site.yml' located in the '.github/workflows/' directory, which is responsible for deploying documentation to GitHub Pages. The file includes triggers for pushes to the 'main' branch and permissions for deployment.]

[Progress Assessment: The user has outlined a clear plan for deployment but has not yet implemented the Bicep deployment process or the CI/CD workflow for Azure SWA. The existing GitHub workflow for documentation deployment is in place.]

[Context Validation: All necessary context for continuing the discussion on deploying the wiki to Azure SWA is captured, including user goals and the existing GitHub workflow.]

[Recent Commands Analysis: The last agent command executed was 'semantic_search', which was used to explore deployment options for the Azure SWA. The tool results have not been provided, but the command was executed in the context of the user's request for deployment guidance. The agent was actively working on understanding the deployment process when the token budget was exceeded.]

1. Conversation Overview: - Primary Objectives: The user aims to deploy their wiki to Azure Static Web Apps (SWA) and create a streamlined process for others to clone the repository, modify parameters, and deploy using Bicep. They stated, "I kind of would like to package up this repo as an easy-to-hand out scenario to people." - Session Context: The conversation has focused on deployment strategies, CI/CD workflows, and leveraging existing GitHub Actions for documentation updates. - User Intent Evolution: The user has consistently sought a straightforward deployment process that allows for easy updates and collaboration.

2. Technical Foundation:

• Azure Static Web Apps: A service for hosting static websites, which the user wants to utilize for their wiki.
• Bicep: An infrastructure as code tool that the user intends to use for deploying the SWA.
• GitHub Actions: The user is leveraging GitHub workflows for CI/CD, specifically for deploying documentation.

3. Codebase Status:

• File Name: publish-site.yml
• Purpose: This file is responsible for deploying documentation to GitHub Pages.
• Current State: The workflow is set up to trigger on pushes to the 'main' branch and has permissions for deployment.
• Key Code Segments: Includes triggers for the 'docs/**' path and permissions for GitHub Pages deployment.

4. Problem Resolution:

• Issues Encountered: The user has not yet implemented the Bicep deployment process or CI/CD workflow for Azure SWA.
• Solutions Implemented: The existing GitHub workflow for documentation deployment is functioning.
• Debugging Context: No specific debugging issues have been mentioned, but the user is seeking guidance on deployment.

5. Progress Tracking:

• Completed Tasks: The GitHub workflow for documentation deployment is in place.
• Partially Complete Work: The Bicep deployment process and CI/CD workflow for Azure SWA are yet to be implemented.
• Validated Outcomes: The existing workflow for GitHub Pages is confirmed to be working.

6. Active Work State:

• Current Focus: The user is focused on deploying the wiki to Azure SWA and creating a CI/CD workflow.
• Recent Context: The user executed the 'semantic_search' tool to explore deployment options for Azure SWA.
• Working Code: The user is considering modifications to the Bicep parameter file and the CI/CD workflow.
• Immediate Context: The user is looking for a streamlined deployment process for Azure SWA.

7. Recent Operations:

• Last Agent Commands: The last command executed was 's...

Created from VS Code.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This pull request implements Azure Static Web Apps deployment as an alternative hosting option to the existing GitHub Pages setup. The implementation provides Infrastructure as Code using Bicep templates, an automated deployment script, a comprehensive CI/CD pipeline via GitHub Actions, and extensive documentation to enable easy forking and self-hosting.

Changes:

• Adds complete Azure Static Web Apps infrastructure using Bicep with parameterized configuration for easy customization
• Implements automated CI/CD pipeline with PR preview environments and automatic cleanup
• Provides comprehensive documentation with step-by-step deployment guide and troubleshooting section

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
.github/workflows/azure-swa-deploy.yml	New GitHub Actions workflow for building DocFX and deploying to Azure SWA with PR preview support
staticwebapp.config.json	Runtime configuration for Azure SWA including navigation fallback, cache headers, and 404 handling
infra/main.bicep	Bicep template defining Azure Static Web App resource with parameterized SKU, location, and tags
infra/bicep.parameters.json	Single customization point for infrastructure deployment with default values
infra/README.md	Infrastructure-specific deployment instructions with Azure CLI commands
deploy-azure.sh	Automated deployment script with prerequisite checks, interactive prompts, and token retrieval
DEPLOYMENT.md	Comprehensive step-by-step deployment guide with troubleshooting and cost estimates
README.md	Updated to document both GitHub Pages and Azure SWA deployment options
.gitignore	Added exclusions for Azure artifacts and Bicep build outputs

[Copilot]

The deployment script outputs placeholder text "YOUR-USERNAME/YOUR-REPO" in the instructions, which requires manual replacement by users. Consider making the script more intelligent by attempting to extract the actual repository information from git remote or environment variables, or at minimum add a clear comment/warning that users need to replace these placeholders with their actual GitHub username and repository name.