Build & Deploy SPFx package in multiple environments (GitHub Actions & PnP PowerShell)

build-spfx.yml

name: build

on:
  workflow_call:  # only callable from another workflow
    inputs:
      include_tests:
        description: 'Indicates whether build job has to run tests or not'
        default: false
        required: false
        type: string

jobs:
  build: # job name here, can be anything else
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Use Node 14.x
        uses: actions/setup-node@v2
        with:
          node-version: '14'
          cache: 'npm'

      - name: npm ci
        run: npm ci

      - name: Bundle project
        run: gulp bundle --ship

      - name: npm test
        if: ${{ inputs.include_tests == true }}
        run: npm test

      - name: Package solution
        run: gulp package-solution --ship

      - name: Upload artifact for deployment job
        uses: actions/upload-artifact@v2
        with:
          path: sharepoint/solution/*.sppkg

deploy-spfx-pnp-powershell.yml

name: deploy with pnp powershell

on:
  workflow_call:
    inputs:
      environment_name:
        description: 'Target environment to deploy to'
        required: true
        type: string
      site_url_prd:
        description: 'SharePoint PRD site URL'
        required: false
        type: string
      site_url_uat:
        description: 'SharePoint UAT site URL'
        required: false
        type: string
      app_catalog_scope:
        description: 'Indicates the PRD app catalog scope (tenant or site collection)'
        default: ""
        required: false
        type: string
    secrets:
      AAD_APP_ID:
        required: true
      AAD_APP_PASSWORD:
        required: true
      AAD_APP_ENCODED_CERTIFICATE:
        required: true
      AAD_TENANT_ID:
        required: true

jobs:
  deploy:
    runs-on: windows-2022
    environment: ${{ inputs.environment_name }}
    steps:
      - name: Download artifact from build job
        uses: actions/download-artifact@v2

      - name: Installing PnP.PowerShell Module
        shell: pwsh
        run: Install-Module -Name "PnP.PowerShell" -Force

      - name: Get generated *.sppkg filename
        id: package
        shell: pwsh
        run: |
            $package = Get-ChildItem -Path artifact -Recurse -Filter '*.sppkg' | Select Name | Select-Object -First 1
            echo "::set-output name=name::$($package.Name)"

      - name: Upload & deploy SharePoint package to ${{ inputs.app_catalog_scope }} App Catalog (${{ inputs.environment_name }})
        run: |
          $siteUrl = "${{ inputs.site_url_uat }}"
          $appCatalogScope = "Site"

          if ('${{ inputs.environment_name }}' -eq 'PRD') {
            $siteUrl = "${{ inputs.site_url_prd }}"
            $appCatalogScope = "${{ inputs.app_catalog_scope }}"
          }

          $securePassword = ConvertTo-SecureString "${{ secrets.AAD_APP_PASSWORD }}" -AsPlainText -Force
          Connect-PnPOnline -Url $siteUrl -CertificateBase64Encoded ${{ secrets.AAD_APP_ENCODED_CERTIFICATE }} -CertificatePassword $securePassword -ClientId ${{ secrets.AAD_APP_ID }} -Tenant ${{ secrets.AAD_TENANT_ID }}
          Add-PnPApp -Path "artifact/${{ steps.package.outputs.name }}" -Scope $appCatalogScope -Publish -Overwrite

main.yml

    name: main
    
    on:
      push:
        branches: 
        - main
      workflow_dispatch: # Can be triggered manually

    jobs:
      build:
        uses: meganb/helloworld/.github/workflows/build-spfx.yml@main
      deploy_uat:
        needs: build
        uses: meganb/helloworld/.github/workflows/deploy-spfx-pnp-powershell.yml@main
        with:
          environment_name: UAT
          site_url_uat: https://contoso.sharepoint.com/sites/CommSite-UAT
        secrets:
          AAD_APP_ID: ${{ secrets.AAD_APP_ID }}
          AAD_APP_PASSWORD: ${{ secrets.AAD_APP_PASSWORD }}
          AAD_APP_ENCODED_CERTIFICATE: ${{ secrets.AAD_APP_ENCODED_CERTIFICATE }}
          AAD_TENANT_ID: ${{ secrets.AAD_TENANT_ID }}
      deploy_prd:
        needs: deploy_uat
        uses: meganb/helloworld/.github/workflows/deploy-spfx-pnp-powershell.yml@main
        with:
          environment_name: PRD
          site_url_prd: https://contoso.sharepoint.com/sites/CommSite
          app_catalog_scope: tenant
        secrets:
          AAD_APP_ID: ${{ secrets.AAD_APP_ID }}
          AAD_APP_PASSWORD: ${{ secrets.AAD_APP_PASSWORD }}
          AAD_APP_ENCODED_CERTIFICATE: ${{ secrets.AAD_APP_ENCODED_CERTIFICATE }}
          AAD_TENANT_ID: ${{ secrets.AAD_TENANT_ID }}

Abstract

This sample provides a ready-to-use GitHub Action workflow that will build an SPFx package, then deploy it on an existing site (in a site collection app catalog) dedicated to test out new features / bug fixes. Then the pipeline will be deployed on the tenant app catalog (or a production site collection app catalog). This sample will use PnP PowerShell in order to connect to SharePoint Online and deploy the SPFx package. Below the different files description:

• main.yml: the main pipeline that will be triggered as the initiator
• build-spfx.yml: CI pipeline
• deploy-spfx-pnp-powershell.yml: CD pipeline

Configuration

Solution

The SPFx solution can be ordered like this:

│   .gitignore
│   .npmignore
│   .yo-rc.json
│   gulpfile.js
│   package-lock.json
│   package.json
│   README.md
│   tsconfig.json
│   tslint.json
│
├───.github
│   └───workflows
│          build-spfx.yml  --------> CI pipeline
│          deploy-spfx-pnp-powershell.yml  --------> CD pipeline
│          main.yml  --------> main pipeline
│
├───.vscode
│
├───config
│
├───src
│   │   index.ts
│   │
│   └───webparts
│       └───helloWorld
│           │   HelloWorldWebPart.manifest.json
│           │   HelloWorldWebPart.ts
│           │
│           ├───components
│           │       HelloWorld.module.scss
│           │       HelloWorld.module.scss.ts
│           │       HelloWorld.tsx
│           │       IHelloWorldProps.ts
│           │
│           └───loc
│                   en-us.js
│                   mystrings.d.ts
│
├───teams

Environments

The environments will be necessary for approving a pipeline before being run. You'll have to add two environments:

• UAT (testing)
• PRD (production)

Environments can be configured here: https://github.com/[ORGANIZATION]/[PROJECT]/settings/environments.

/!\ Beware that in order to use multiple environments, your repo has to be public or your subscription has to be a Pro one.

Approvers

For each environment, you can add an approver by enabling the checkbox marked "Required reviewers", then adding at least one reviewer account then click on "Save protection rules".

Environment secrets

Environment secrets can be configured here: https://github.com/[ORGANIZATION]/[PROJECT]/settings/environments/[ENVIRONMENT_ID]/edit.

Below the secrets used in the workflows:

Name	Description
AAD_APP_ID	The Azure AD application ID with which the authentication to SharePoint will be done
AAD_APP_PASSWORD	The certificate password necessary for the authentication
AAD_APP_ENCODED_CERTIFICATE	Base64 encoded certificate
AAD_TENANT_ID	ID or domain (for example "contoso.onmicrosoft.com") of the tenant from which accounts should be able to authenticate

CD Workflow parameters

Below the parameters used in the deploy-spfx-pnp-powershell.yml workflow, depending on the environment:

Name	UAT	PRD	Definition
environment_name	YES	YES	The deployment environment (can be 'UAT' or 'PRD')
site_url_uat	YES	NO	SharePoint UAT site URL where the SPFx package will be deployed
site_url_prd	NO	YES	SharePoint PRD site URL where the SPFx package will be deployed
app_catalog_scope	NO	YES	Production app catalog scope (can be "tenant" or "site collection")