Azure Pipeline Templates for SharePoint Framework Projects

This repo contains templates for SharePoint Framework (SPFx) projects using Azure DevOps Pipelines.

Included Templates

• ./jobs/build.yml: Used for building, bundling & creating the SharePoint *.sppkg file for your project.
• ./jobs/test.yml: Used to execute your tests & publish the resulting JUnit & code coverage report.
• ./jobs/deploy.yml: Used to upload & deploy the SharePoint package *.sppkg file to the specified App Catalog site (both tenant & site collection scoped are support).

See the sample SPFx project ./sample configured with an Azure DevOps Pipeline that uses these templates.

Usage

Follow these steps to use the templates in your SPFx project Azure pipeline.

Step 1: Import job templates into your Azure pipeline

Add a repository resource

# azure-pipelines.yml
resources:
  repositories:
  - repository: azure-pipelines-spfx-templates
    type: github
    name: voitanos/azure-pipelines-spfx-templates
    ref: refs/tags/v1.0.0
    endpoint: github

Note: If you do not have a github service connection in the project hosting your pipeline (or you do not have access to it), you can create one via Project Settings. Just make sure the name of this service connection is specified in the endpoint field. See service connections for more details.

The sample project's service connection is named voitanos-github, as it points to this org's repo. The name is entirely up to you though.

Important: Consider Referencing Specific Template Versions

It is strongly recommended to include the ref property as shown above. This points to a specific branch or tag so your pipelines are based on specific templates. To pull from a specific release, use ref: refs/tags/v1.0.0. To pull from a specific branch, use ref: refs/heads/branch-name.

To use the latest version of the templates, omit the ref property to always pull the master branch.

Step 2: Add the job templates to your Azure pipeline

Create a stage for building the project that contains the template:

# azure-pipelines.yml
- stage: Build
  dependsOn: []
  jobs:
    - template: jobs/build.yml@azure-pipelines-spfx-templates

Create a stage for testing the project that contains the template:

# azure-pipelines.yml
- stage: Test
  dependsOn: []
  jobs:
    - template: jobs/test.yml@azure-pipelines-spfx-templates

Create a stage for deploying the project that contains the template:

# azure-pipelines.yml
- stage: Deploy
  dependsOn:
    - Build
    - Test
  jobs:
    - template: jobs/deploy.yml@azure-pipelines-spfx-templates
      parameters:
        target_environment: development
        m365_user_login: [email protected]
        m365_user_password: <password>
        m365_app_catalog_site_url: https://contoso.sharepoint.com/sites/AppCatalog
        m365cli_app_catalog_scope: tenant
        m365cli_deploy_extra_arguments: '--skipFeatureDeployment'

Templates

This project includes the following templates:

jobs/build.yml

This job template does the following:

1. Install all dependencies using Yarn
2. Build the project using gulp build
3. Bundle the project using gulp bundle --ship
4. Package the solution using gulp package-solution --ship
5. Determine the name of the generated *.sppkg
6. Publish the resulting *.sppkg as a build artifact named spfx-package to the pipeline run

Parameters

NOTE: Refer to the sample project for examples of how to set the pool & working_directory properties to different values when (1) you want to use a different agent pool, such as self-hosted agents (like the sample uses) or (2) when your project resides in a subfolder.

jobs/test.yml

This job template does the following:

1. Install all dependencies using Yarn

2. Build the project using gulp build

   Required when using Jest to test rendered React components to work around an issue with the un-build *.scss.ts file. This build step will build that file so the Jest React component rendering tests won't fail.

3. Execute the tests using the project's test command defined in the package.json's scripts property.

4. Publish the resulting JUnit test report as a test result artifact to the pipeline run

5. Publish the resulting Cobertura code coverage report as a code coverage result artifact to the pipeline run

Parameters

NOTE: Refer to the sample project for examples of how to set the pool & working_directory properties to different values when (1) you want to use a different agent pool, such as self-hosted agents (like the sample uses) or (2) when your project resides in a subfolder.

jobs/deploy.yml

This job template does the following:

1. Install Office 365 CLI
2. Login to Office 365 CLI
3. Download previously built SharePoint package
4. Determine the name of the generated *.sppkg
5. Upload *.sppkg to specified SharePoint App Catalog
6. Deploy *.sppkg in the specified SharePoint App Catalog

Parameters

NOTE: Refer to the sample project for examples of how to set the pool property to different values when you want to use a different agent pool, such as self-hosted agents (like the sample uses).

Limitations

1. The templates use the Microsoft hosted Linux agent Ubuntu.