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
Set up pipelines
You can set up pipelines with the following platforms:
- Set up workflows with GitHub
- Set up pipelines with Azure DevOps
- Set up pipelines with Jenkins
- 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/update resources in cloud and Teams app registrations.
- Publish - Hellp publish Teams app to tenants.
Prepare credentials
Two categories of login credentials are involved in CI/CD workflows:
- M365 - M365 credentails 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.
Azure subscription id is required to be set in environment variable or
env/.env.*
files before running Provision workflows. The variable name used isAZURE_SUBSCRIPTION_ID
. Also, please don't forget to commit and push filesenv/.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
- Download the corresponding template files from Tools and Templates.
- Rename the downloaded template files by your needs.
- Put them under
.github/workflows
which is the designated folder for GitHub Actions. - Commit and push these template files into remote repositories.
- Add necessary encrypted secrets for your workflows.
- 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:
- Change the trigger - By default, the CI workflow is triggered when a new pull request is created against
dev
branch. - Add scripts to build the project - By default, the
Build the project
step is commented. - 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:
- Change the trigger - By default, the CD workflow is triggered when new commits are pushed into
main
branch. - Change the value of environment variable
TEAMSFX_ENV_NAME
- By default, the value isdev
. - Change the value of environment variable
TEAMSFX_CLI_VERSION
- By default, the value is2.*
. - Add scripts to build the project - By default, the
Build the project
step is commented. - 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:
- Change the trigger - By default, the workflow is triggered manually.
- Change the value of environment variable
TEAMSFX_ENV_NAME
- By default, the value isdev
. - Change the value of environment variable
TEAMSFX_CLI_VERSION
- By default, the value is2.*
.
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
- Download the corresponding template files from Tools and Templates.
- Rename the downloaded template files by your needs.
- Put them under
.azure/pipelines
which is the conventional folder for Azure Pipelines. - Commit and push these template files into remote repositories.
- Create corresponding Azure DevOps pipelines by following Create your first Azure DevOps Pipeline.
- Add necessary Azure DevOps Pipeline variables for your pipelines.
- Trigger your pipelines automatically, manually or do customization (Check the
trigger:
orpr:
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:
- Change the trigger - By default, the CI pipeline is triggered when a new pull request is created against
dev
branch. - Add scripts to build the project - By default, the
Build the project
step is commented. - 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:
- Change the trigger - By default, the CD pipeline is triggered when new commits are pushed into
main
branch. - Change the value of environment variable
TEAMSFX_ENV_NAME
- By default, the value isdev
. - Change the value of environment variable
TEAMSFX_CLI_VERSION
- By default, the value is2.*
. - Add scripts to build the project - By default, the
Build the project
step is commented. - 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:
- Change the trigger - By default, the workflow is triggered manually.
- Change the value of environment variable
TEAMSFX_ENV_NAME
- By default, the value isdev
. - Change the value of environment variable
TEAMSFX_CLI_VERSION
- By default, the value is2.*
.
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
- Download the corresponding template files from Tools and Templates.
- Rename the downloaded template files by your needs.
- 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:
- Change the trigger - By default, the CI pipeline is triggered periodically.
- Add scripts to build the project - By default, the
Build the project
step is commented. - 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:
- Change the trigger - By default, the CD pipeline is triggered periodically.
- Change the value of environment variable
TEAMSFX_ENV_NAME
- By default, the value isdev
. - Change the value of environment variable
TEAMSFX_CLI_VERSION
- By default, the value is2.*
. - Add scripts to build the project - By default, the
Build the project
step is commented. - 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:
- Change the trigger - By default, the pipeline is triggered periodically.
- Change the value of environment variable
TEAMSFX_ENV_NAME
- By default, the value isdev
. - Change the value of environment variable
TEAMSFX_CLI_VERSION
- By default, the value is2.*
.
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 onCI_ENABLED
byexport 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:
- Register an Microsoft Entra application in single tenant.
- Assign a role to your Microsoft Entra application to access your Azure subscription. The
Contributor
role is recommended. - 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:
- Sign-in to Developer portal for Teams using the corresponding account.
- Import your app package in zip, select
App -> Import app -> Replace
. - Select the target app in app list.
- Publish your app, select
Publish -> Publish to your org
.