How to automate cicd pipelines - OfficeDev/TeamsFx GitHub Wiki

Set up CI/CD pipelines

TeamsFx helps to automate your development workflow while building Teams applications. The following are the tools and templates you can use to set up CI/CD pipelines, create workflow templates, and customize CI/CD workflow with GitHub, Azure DevOps, Jenkins, and other platforms. To provision resources, you can create Azure service principals and use the Provision pipeline or do it mannually by leveraging bicep files. To publish Teams app, you can use the Publish pipeline or do it mannually by leveraging Developer Portal for Teams.

Tools and Templates

Tools and Templates Description
TeamsFx-CLI-Action GitHub action that integrates with TeamsFx CLI.
Teams Toolkit for Visual Studio Code Visual Studio Code extension that helps you to develop Teams app and automation workflows for GitHub, Azure DevOps, and Jenkins.
Teams Toolkit for CLI Command Line tool that helps you to develop Teams app and automation workflows for GitHub, Azure DevOps, and Jenkins.
github/ci.ymlgithub/cd.azure.ymlgithub/cd.spfx.ymlgithub/provision.azure.ymlgithub/provision.spfx.ymlgithub/publish.yml Templates for automation on GitHub
azdo/ci.ymlazdo/cd.azure.ymlazdo/cd.spfx.ymlazdo/provision.azure.ymlazdo/provision.spfx.ymlazdo/publish.yml Templates for automation on Azure DevOps
jenkins/Jenkinsfile.cijenkins/Jenkinsfile.azure.cdjenkins/Jenkinsfile.spfx.cdjenkins/Jenkinsfile.azure.provisionjenkins/Jenkinsfile.spfx.provisionjenkins/Jenkinsfile.publish Templates for automation on Jenkins
others/ci.shothers/cd.azure.shothers/cd.spfx.shothers/provision.azure.shothers/provision.spfx.shothers/publish.sh Script templates for automation outside of GitHub, Azure DevOps or Jenkins

Set up pipelines

You can set up pipelines with the following platforms:

  1. Set up workflows with GitHub
  2. Set up pipelines with Azure DevOps
  3. Set up pipelines with Jenkins
  4. Set up pipelines for other platforms

Workflow template types

TeamsFx supports four types of workflow templates:

  1. CI - Help checkout code, build and run test.
  2. CD - Help checkout code, build, test and deploy to cloud.
  3. Provision - Help create/update resources in cloud and Teams app registrations.
  4. Publish - Hellp publish Teams app to tenants.

Prepare credentials

Two categories of login credentials are involved in CI/CD workflows:

  1. M365 - M365 credentails are required for running Provision, Publish and SPFx based projects' CD workflows.
  2. Azure - Azure credentials are required for running Azure hosted projects' Provision and CD workflows.

Azure subscription id is required to be set in environment variable or env/.env.* files before running Provision workflows. The variable name used is AZURE_SUBSCRIPTION_ID. Also, please don't forget to commit and push files env/.env.* into Git repositories or set pipelines' environment variables as they are ignored by .gitignore file by default.

Name Description
AZURE_SERVICE_PRINCIPAL_NAME The service principal name of Azure used to provision resources.
AZURE_SERVICE_PRINCIPAL_PASSWORD The password of Azure service principal.
AZURE_SUBSCRIPTION_ID To identify the subscription in which the resources will be provisioned.
AZURE_TENANT_ID To identify the tenant in which the subscription resides.
M365_ACCOUNT_NAME The Microsoft 365 account for creating and publishing the Teams App.
M365_ACCOUNT_PASSWORD The password of the Microsoft 365 account.
M365_TENANT_ID To identify the tenant in which the Teams App will be created/published. This value is optional unless you have a multi-tenant account and you want to use another tenant. Read more on how to find your Microsoft 365 tenant ID.

Currently, a non-interactive authentication style for Microsoft 365 is used in CI/CD workflows, so please ensure that your Microsoft 365 account has sufficient privileges in your tenant and doesn't have multi-factor authentication or other advanced security features enabled. Please refer to the Configure Microsoft 365 Credentials to make sure you have disabled Multi-factor Authentication and Security Defaults for the credentials used in the workflow.

Currently, service principal for Azure is used in CI/CD workflows, and to create Azure service principals for use, refer to here.

Host types

Templates varies in host types (Azure or SPFx) by which Provision and CD workflow templates are splited into copies. CI, Publish workflow templates are host-type independent. If you're working on Azure hosted projects, please download those templates with file name of azure infixes. Or if you're working on SPFx hosted projects, please download those templates with file name of spfx infixes.

Set up workflows with GitHub

To set up pipelines with GitHub for CI/CD:

  • Create CI/CD workflows.
  • Customize CI/CD workflows.

Create CI/CD workflows

  1. Download the corresponding template files from Tools and Templates.
  2. Rename the downloaded template files by your needs.
  3. Put them under .github/workflows which is the designated folder for GitHub Actions.
  4. Commit and push these template files into remote repositories.
  5. Add necessary encrypted secrets for your workflows.
  6. Trigger your workflows. Check more details about how to trigger a workflow on GitHub.

Customize CI workflow

To customize the CI workflow, you can do the following:

  1. Change the trigger - By default, the CI workflow is triggered when a new pull request is created against dev branch.
  2. Add scripts to build the project - By default, the Build the project step is commented.
  3. Add scripts to run unit test - By default, the Run unit test step is commented.

Customize CD workflow

To customize the CD workflow, you can do the following:

  1. Change the trigger - By default, the CD workflow is triggered when new commits are pushed into main branch.
  2. Change the value of environment variable TEAMSFX_ENV_NAME - By default, the value is dev.
  3. Change the value of environment variable TEAMSFX_CLI_VERSION - By default, the value is 2.*.
  4. Add scripts to build the project - By default, the Build the project step is commented.
  5. Add scripts to run unit test - By default, the Run unit test step is commented.

Customize Provision and Publish workflow

To customize the Provision and Publish workflow, you can do the following:

  1. Change the trigger - By default, the workflow is triggered manually.
  2. Change the value of environment variable TEAMSFX_ENV_NAME - By default, the value is dev.
  3. Change the value of environment variable TEAMSFX_CLI_VERSION - By default, the value is 2.*.

Set up pipelines with Azure DevOps

To set up pipelines with Azure DevOps for CI/CD:

  • Create CI/CD pipelines.
  • Customize CI/CD pipelines.

Create CI/CD pipelines

  1. Download the corresponding template files from Tools and Templates.
  2. Rename the downloaded template files by your needs.
  3. Put them under .azure/pipelines which is the conventional folder for Azure Pipelines.
  4. Commit and push these template files into remote repositories.
  5. Create corresponding Azure DevOps pipelines by following Create your first Azure DevOps Pipeline.
  6. Add necessary Azure DevOps Pipeline variables for your pipelines.
  7. Trigger your pipelines automatically, manually or do customization (Check the trigger: or pr: section in yml files to find the triggers). More about triggers in Azure DevOps, refer to Triggers in Azure pipelines.

Customize CI pipeline

To customize the CI pipeline, you can do the following:

  1. Change the trigger - By default, the CI pipeline is triggered when a new pull request is created against dev branch.
  2. Add scripts to build the project - By default, the Build the project step is commented.
  3. Add scripts to run unit test - By default, the Run unit test step is commented.

Customize CD pipeline

To customize the CD pipeline, you can do the following:

  1. Change the trigger - By default, the CD pipeline is triggered when new commits are pushed into main branch.
  2. Change the value of environment variable TEAMSFX_ENV_NAME - By default, the value is dev.
  3. Change the value of environment variable TEAMSFX_CLI_VERSION - By default, the value is 2.*.
  4. Add scripts to build the project - By default, the Build the project step is commented.
  5. Add scripts to run unit test - By default, the Run unit test step is commented.

Customize Provision and Publish pipelines

To customize the Provision and Publish pipeline, you can do the following:

  1. Change the trigger - By default, the workflow is triggered manually.
  2. Change the value of environment variable TEAMSFX_ENV_NAME - By default, the value is dev.
  3. Change the value of environment variable TEAMSFX_CLI_VERSION - By default, the value is 2.*.

Set up pipelines with Jenkins

To set up pipelines with Jenkins for CI/CD:

  • Create CI/CD pipelines.
  • Customize CI/CD pipelines.

Create CI/CD pipelines

  1. Download the corresponding template files from Tools and Templates.
  2. Rename the downloaded template files by your needs.
  3. Put them under .jenkins/pipelines which can be a conventional folder for Jenkins Pipelines.

Customize CI pipeline

To customize the CI pipeline, you can do the following:

  1. Change the trigger - By default, the CI pipeline is triggered periodically.
  2. Add scripts to build the project - By default, the Build the project step is commented.
  3. Add scripts to run unit test - By default, the Run unit test step is commented.

Customize CD pipeline

To customize the CD pipeline, you can do the following:

  1. Change the trigger - By default, the CD pipeline is triggered periodically.
  2. Change the value of environment variable TEAMSFX_ENV_NAME - By default, the value is dev.
  3. Change the value of environment variable TEAMSFX_CLI_VERSION - By default, the value is 2.*.
  4. Add scripts to build the project - By default, the Build the project step is commented.
  5. Add scripts to run unit test - By default, the Run unit test step is commented.

Customize Provision and Publish pipelines

To customize the Provision and Publish pipeline, you can do the following:

  1. Change the trigger - By default, the pipeline is triggered periodically.
  2. Change the value of environment variable TEAMSFX_ENV_NAME - By default, the value is dev.
  3. Change the value of environment variable TEAMSFX_CLI_VERSION - By default, the value is 2.*.

Set up pipelines for other platforms

You can follow the predefined listed example bash scripts from Tools and Templates to build and customize CI/CD pipelines on the other platforms:

The scripts are based on a cross-platform TeamsFx command line tool TeamsFx-CLI. You can install it with npm install -g @microsoft/teamsfx-cli and follow the documentation to customize the scripts.

  • To enable @microsoft/teamsfx-cli running in CI mode, turn on CI_ENABLED by export CI_ENABLED=true. In CI mode, @microsoft/teamsfx-cli is friendly for CI/CD.
  • To enable @microsoft/teamsfx-cli running in the non-interactive mode, set a global config with command: teamsfx config set -g interactive false. In the non-interactive mode, @microsoft/teamsfx-cli does not prompt for inputs.

Ensure to set up Azure and Microsoft 365 credentials in your environment variables safely. For example, if you're using GitHub as your source code repository, see GitHub Secrets.

Setup pipeline for Azure Static Web Apps

To setup the CI/CD pipeline for Azure Static Web Apps, please refer to Azure Static Web Apps' official site to find solution.

How to create Azure service principals for use?

To provision and deploy resources targeting Azure inside CI/CD, you must create an Azure service principal for use.

Perform the following steps to create Azure service principals:

  1. Register an Microsoft Entra application in single tenant.
  2. Assign a role to your Microsoft Entra application to access your Azure subscription. The Contributor role is recommended.
  3. Create a new Microsoft Entra application secret.

Save your tenant id, application id (AZURE_SERVICE_PRINCIPAL_NAME), and the secret (AZURE_SERVICE_PRINCIPAL_PASSWORD) for future use.

For more information, see Azure service principals guidelines. The following are the three ways to create service principals:

Publish Teams app using Teams Developer Portal

If there are any changes related to Teams app's manifest file, you can update the manifest and publish the Teams app again. To publish Teams app manually, you may leverage Developer Portal for Teams.

Perform the following steps to publish your app:

  1. Sign-in to Developer portal for Teams using the corresponding account.
  2. Import your app package in zip, select App -> Import app -> Replace.
  3. Select the target app in app list.
  4. Publish your app, select Publish -> Publish to your org.

See also