Self-Hosted CICD Runners Guidance (#70)

* Modified publish workflow path

* Added section on self-hosted runners guidance

---------

Co-authored-by: Adin Ermie <[email protected]>

.github/workflows/publish-dev.yaml

@@ -6,7 +6,7 @@ on:
         branches: [ dev ]
         paths:
             - "mkdocs.yml"
-            - "docs/*"
+            - "docs/**"
 
 jobs:
     test_techdocs_build_job:

.github/workflows/publish-prod.yaml

@@ -6,7 +6,7 @@ on:
         branches: [ main ]
         paths:
             - "mkdocs.yml"
-            - "docs/*"
+            - "docs/**"
 
 jobs:
     test_techdocs_build_job:

docs/azure/best-practices/ci-cd.md

@@ -6,12 +6,12 @@ Last updated: **{{ git_revision_date_localized }}**
 
 If you are using GitHub Actions for your CI/CD pipeline, consider the following best practices:
 
-* Use [OpenID Connect (OIDC) authentication](#configuring-github-action-oidc-authentication-to-azure) for GitHub Actions to authenticate with Azure.
-
-* [Self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on Azure are required to access data storage and database services from GitHub Actions. Public access to these services is not supported.
+* Configure [OpenID Connect (OIDC) authentication](#configuring-github-action-oidc-authentication-to-azure) for GitHub Actions to authenticate with Azure.
 
 * If using [Terraform](https://www.terraform.io/), be aware of the limitations when [creating Subnets](../best-practices/be-mindful.md#using-terraform-to-create-subnets), and the use of the [AzAPI Terraform Provider](be-mindful.md#azapi-terraform-provider-using-azapi_update_resource).
 
+* [Self-hosted runners](#self-hosted-runners-on-azure) on Azure are required to access data storage and database services from GitHub Actions. Public access to these services is not supported.
+
 ### Configuring GitHub Action OIDC Authentication to Azure
 
 To allow GitHub Actions to securely access Azure subscriptions, use OpenID Connect (OIDC) authentication.
@@ -23,8 +23,8 @@ Here's a quick summary on how to set it up:
 1. The GitHub Identity Provider has already been configured in the Azure subscriptions in your Project Set
 2. In your Azure subscription:
 
-  - Create an Entra ID application and a service principal
-  - Add federated credentials for the Entra ID application
+  - Create an Entra ID Application and a Service Principal
+  - Add federated credentials for the Entra ID Application
   - Create GitHub secrets for storing Azure configuration
 
 3. In your GitHub workflows:
@@ -33,3 +33,20 @@ Here's a quick summary on how to set it up:
   - Use the [azure/login](https://github.com/Azure/login) action to exchange the OIDC token (JWT) for a cloud access token
 
 This allows GitHub Actions to authenticate to Azure and access resources.
+
+### Self-Hosted Runners on Azure
+
+Microsoft has created an [Azure Verified Module (AVM) for CICD Agents and Runners](https://github.com/Azure/terraform-azurerm-avm-ptn-cicd-agents-and-runners). The Public Cloud team has tested this module, and verified that it works within our Azure environment (with a few customizations).
+
+We have created a dedicated/centralized GitHub repository to provide sample Terraform code for creating various application patterns, and various tools. This repository is called [Azure Landing Zone Samples (azure-lz-samples)](https://github.com/bcgov/azure-lz-samples).
+
+You can find the sample Terraform code for deploying self-hosted GitHub runners in the `/tools/cicd_self_hosted_agents/` directory.
+
+!!! info "Pre-requisites"
+    Please take special note of the pre-requisites listed in the README file in the `/tools/cicd_self_hosted_agents/` directory. It describes the necessary subnets that the self-hosted runners need to be deployed in.
+
+!!! question "Cross-Subscription Access"
+    If you plan to deploy the self-hosted runners into a different Azure subscription than where your resources will be deployed (ie. in your **Tools** subscription), you will need to [submit a firewall request](https://citz-do.atlassian.net/servicedesk/customer/portal/3) to the Public Cloud team. This request will allow the self-hosted runners to access the necessary resources in the other subscription.
+
+!!! note ""
+   When using the [Azure Verified Module (AVM) for CICD Agents and Runners](https://github.com/Azure/terraform-azurerm-avm-ptn-cicd-agents-and-runners) (or any other modules), Terraform may show that it will remove certain tags from resources. This is because the module is not aware of the tags that are set on the resources. If you want to keep the tags, you can add a `lifecycle` block with the [ignore_changes](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes) feature, to the resource in your Terraform code to ignore the tags.