Edit

Set up CI/CD pipelines

  • Article

TeamsFx helps to automate your development workflow while building Teams application. The tools and templates to set up CI/CD pipelines are 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 manually by leveraging bicep files. To publish Teams app, you can use the Publish pipeline or do it manually 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.yml
github/cd.azure.yml
github/cd.spfx.yml
github/provision.azure.yml
github/provision.spfx.yml
github/publish.yml		 Templates for automation on GitHub.
azdo/ci.yml
azdo/cd.azure.yml
azdo/cd.spfx.yml
azdo/provision.azure.yml
azdo/provision.spfx.yml
azdo/publish.yml		 Templates for automation on Azure DevOps.
jenkins/Jenkinsfile.ci
jenkins/Jenkinsfile.azure.cd
jenkins/Jenkinsfile.spfx.cd
jenkins/Jenkinsfile.azure.provision
jenkins/Jenkinsfile.spfx.provision
jenkins/Jenkinsfile.publish		 Templates for automation on Jenkins.
others/ci.sh
others/cd.azure.sh
others/cd.spfx.sh
others/provision.azure.sh
others/provision.spfx.sh
others/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:

  • CI: Help checkout code, build, and run test.
  • CD: Help checkout code, build, test, and deploy to cloud.
  • Provision: Help create or update resources in cloud and Teams app registrations.
  • Publish: Help publish Teams app to tenants.

Prepare credentials

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

  • Microsoft 365: Microsoft 365 credentials are required for running Provision, Publish, and SPFx based projects' CD workflows.
  • Azure: Azure credentials are required for running Azure hosted projects' Provision and CD workflows.

Note

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, don't forget to commit and push files env/.env.* into Git repositories or set pipelines' environment variables as they're 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 are to 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 gets created or 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.

Note

  • Currently, a non-interactive authentication style for Microsoft 365 is used in CI/CD workflows, so 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. 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 vary in host types (Azure or SPFx) by which Provision and CD workflow templates are split into copies. CI, Publish workflow templates are host-type independent. If you're working on Azure hosted projects, download those templates with file name of azure infixes. If you're working on SPFx hosted projects, 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 customize (Check the trigger: or pr: section in yml files to find the triggers). For more information about triggers in Azure DevOps, see 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.

Note

  • 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 doesn't 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.

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 a Microsoft Azure Active Directory (Azure AD) application in single tenant.
  2. Assign a role to your Azure AD application to access your Azure subscription. The Contributor role is recommended.
  3. Create a new Azure AD application secret.

Tip

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. To publish your app, select Publish > Publish to your org.

See also