GitHub Actions - SharePoint Framework CI/CD

The SharePoint Framework (SPFx) is Microsoft's development model for creating custom web parts in SharePoint Online. It can greatly expand SharePoint's capabilities - something out-of-the-box SharePoint Online desperately needs.

This guide will walk you through the creation of a basic CI/CD pipeline for SharePoint development. The GitHub Action workflow will build and deploy custom SharePoint web parts directly to your tenant.

• Why write SPFx web parts?
• Azure Active Directory prerequisites
  • Service Account
  • Conditional Access
  • Application Consent
• Pipeline walkthrough
  • Workflow triggers
  • Running the job
  • Setup steps
  • Deployment steps
• Wrapping up

Why write SPFx web parts?

You can build some useful web parts and widgets with SPFx.

It can also add features Microsoft should have included standard.

For instance - SharePoint Online does not have a dynamically updating table of contents. You have to type it out manually.

If you want a dynamic table of contents you need a custom web part.

Azure Active Directory prerequisites

Before building the pipeline, a few Azure Active Directory prerequisites must be met.

Service Account

A service account (SA) with the appropriate permissions in SharePoint is required to deploy the .sspkg to the application catalog.

• If targeting a single site, the account will need Site Collection Administrator.
• If targeting the tenant as a whole, the account will likely need SharePoint Administrator.

Unfortunately, we cannot use a service principal/application registration for SharePoint.

Attention: Currently, SharePoint does not support authentication using Azure AD App ID and Secret. CLI for Microsoft 365 commands that call the SharePoint APIs will fail while logged in to Microsoft 365 using a Secret.

See the documentation for additional information on this limitation.

Conditional Access

Conditional Access rules should be configured allowing the SA access only if certain conditions are met.

I would highly recommend building a policy leveraging some or all of these rules:

• Identity (i.e. apply only to the SA)
• Trusted IP ranges
• Runner OS
• Cloud Application (31359c7f-bd7e-475c-86db-fdb8c937548e)

Application Consent

The SA will need application consent to login to the PnP Management Shell. Run the PowerShell commands below in the Azure Cloud Shell.

Install-Module PnP.PowerShell
Register-PnPManagementShellAccess

You may not be able to perform these actions in a development M365 tenant - the developer instance prohibits the use of the Cloud Shell.

Pipeline walkthrough

Now that the prerequisites have been addressed, we will dissect the pipeline, spfxpipeline.yaml.

Workflow triggers

The workflow will only begin once a trigger condition has been met, as described by on:

name: "Basic SharePoint Framework Pipeline - Microsoft 365"

on:
  push:
    branches:
      - 'main'
  workflow_dispatch:

This workflow is waiting for one of two events to occur:

1. A push occurs on the main branch.
2. A "workflow_dispatch" is manually triggered - useful when testing.

Once triggered, the workflow will kick off a Job.

Running the job

We start by labeling the job and selecting a runner.

jobs:
  deployment:
    name: 'SPFx Deployment'
    runs-on: self-hosted
    steps:

The runs-on: argument defines the runner our job will execute on.

In the example above, I use a self-hosted runner provisioned within Azure.

Substitute self-hosted with ubuntu-latest to use a GitHub-hosted runner.

Next, steps: define the Job's individual actions.

Setup steps

The first two steps are Actions. Actions are small, purpose built applets.

Action steps are defined with the uses: keyword.

The checkout action is a workflow staple - it clones the repository's code down to the runner.

The setup-node action installs and configures node.

      - name: Checkout
        uses: actions/checkout@v3

      - name: Node.js install
        uses: actions/setup-node@v1
        with:
          node-version: 16.x

The next few steps run commands directly in the runner's shell.

Run steps are defined by the run: keyword.

One step installs NPM (with the CI switch) and the next one installs Gulp globally.

      - name: NPM install
        run: npm ci

      - name: Gulp install
        run: npm i -g gulp

The environment has been configured.

Deployment steps

The runner can now compile our web part. The step below builds our package with two Gulp commands.

      - name: Gulp package
        run: |
          gulp bundle --ship
          gulp package-solution --ship   

The action-cli-login action will authenticate with the service account discussed earlier.

As the SA's credentials are sensitive, the workflow will reference GitHub Action Secrets to inject the credentials into the pipeline as needed.

      - name: M365 login
        id: login
        uses: pnp/action-cli-login@v2.2.1
        with:
          ADMIN_USERNAME:  ${{ secrets.ADMIN_USERNAME }}
          ADMIN_PASSWORD:  ${{ secrets.ADMIN_PASSWORD }}

Finally, the package is deployed to the tenant's SharePoint application catalog using action-cli-deploy.

We specify the package's relative path with APP_FILE_PATH and grant permission to overwrite any existing deployments of the application with OVERWRITE set to true.

      - name: SharePoint deploy
        id: deploy
        uses: pnp/action-cli-deploy@v3.0.1
        with:
          APP_FILE_PATH: ./package/example-web-part.sppkg
          OVERWRITE: true

_{In production, you'd want to replace the hardcoded path and file name with a variable.}

The workflow has completed and the custom web part has been deployed to the tenant.

Wrapping up

As I said back at the beginning of this post, this is a basic pipeline. It is a solid foundation to build upon and not much more.

If you're looking for something more advanced, consider:

• Integrating the workflow with your project management platform of choice.
• Setting up Jest or Enzyme for SPFx unit testing.
• Building a SharePoint UAT environment to pre-stage your deployment.

Thanks for reading!