| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| platform | Use CICD Template | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/use-CICD-template.md | Last updated 04/20/2022 # Set up CI/CD pipelines -TeamsFx helps to automate your development workflow while building Microsoft 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 using bicep files. To publish Teams app, you can use the Publish pipeline or do it manually by leveraging [Developer Portal for Teams](https://dev.teams.microsoft.com/home). +You can set up a Continuous Integration and Continuous Deployment (CI/CD) pipeline for Microsoft Teams apps created with Teams Toolkit. A Teams app CI/CD pipeline consists of three parts: -## Tools and Templates +1. Build the project. -|Tools and Templates | Description | -||| -|[TeamsFx-CLI-Action](https://github.com/OfficeDev/teamsfx-cli-action)|GitHub action that integrates with TeamsFx CLI.| -|[Microsoft Teams Toolkit for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension)| Microsoft Visual Studio Code extension that helps you to develop Teams app and automation workflows for GitHub, Azure DevOps, and Jenkins. | -|[Microsoft Teams Toolkit for CLI](https://www.npmjs.com/package/@microsoft/teamsfx-cli) | Command Line tool that helps you to develop Teams app and automation workflows for GitHub, Azure DevOps, and Jenkins.| -|[github/ci.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/github/ci.yml) <br> [github/cd.azure.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/github/cd.azure.yml) <br> [github/cd.spfx.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/github/cd.spfx.yml) <br> [github/provision.azure.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/github/provision.azure.yml) <br> [github/provision.spfx.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/github/provision.spfx.yml) <br> [github/publish.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/github/publish.yml) | Templates for automation on GitHub.| -|[azdo/ci.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/azdo/ci.yml) <br> [azdo/cd.azure.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/azdo/cd.azure.yml) <br> [azdo/cd.spfx.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/azdo/cd.spfx.yml) <br> [azdo/provision.azure.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/azdo/provision.azure.yml) <br> [azdo/provision.spfx.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/azdo/provision.spfx.yml) <br> [azdo/publish.yml](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/azdo/publish.yml)| Templates for automation on Azure DevOps.| -|[jenkins/Jenkinsfile.ci](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/jenkins/Jenkinsfile.ci) <br> [jenkins/Jenkinsfile.azure.cd](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/jenkins/Jenkinsfile.azure.cd) <br> [jenkins/Jenkinsfile.spfx.cd](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/jenkins/Jenkinsfile.spfx.cd) <br> [jenkins/Jenkinsfile.azure.provision](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/jenkins/Jenkinsfile.azure.provision) <br> [jenkins/Jenkinsfile.spfx.provision](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/jenkins/Jenkinsfile.spfx.provision) <br> [jenkins/Jenkinsfile.publish](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/jenkins/Jenkinsfile.publish) | Templates for automation on Jenkins.| -|[others/ci.sh](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/others/ci.sh) <br> [others/cd.azure.sh](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/others/cd.azure.sh) <br> [others/cd.spfx.sh](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/others/cd.spfx.sh) <br> [others/provision.azure.sh](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/others/provision.azure.sh) <br> [others/provision.spfx.sh](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/others/provision.spfx.sh) <br> [others/publish.sh](https://github.com/OfficeDev/TeamsFx/blob/main/docs/cicd/others/publish.sh) | Script templates for automation outside of GitHub, Azure DevOps, or Jenkins. | +1. Deploy the project to cloud resources. -## Set up pipelines --You can set up pipelines with the following platforms: --1. [Set up workflows with GitHub](#set-up-workflows-with-github) -1. [Set up pipelines with Azure DevOps](#set-up-pipelines-with-azure-devops) -1. [Set up pipelines with Jenkins](#set-up-pipelines-with-jenkins) -1. [Set up pipelines for other platforms](#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. +1. Generate Teams app package. > [!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 multitenant account and you want to use another tenant. Read more on how to find your Microsoft 365 tenant ID.| +> To create a pipeline for a Teams app, it's required to prepare the necessary cloud resources, such as Azure Web App, Azure Functions, or Azure Static Web App, and configure the app settings. -> [!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](https://github.com/OfficeDev/teamsfx-cli-action/blob/main/README.md#configure-m365azure-credentials-as-github-secret) 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](#how-to-create-azure-service-principals-for-use). --## 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 build the project, you must compile the source code and create the required deployment artifacts. There are two methods to deploy the artifacts: -To set up pipelines with GitHub for CI/CD: +* [Set up CI/CD pipelines with Teams Toolkit CLI](#set-up-cicd-pipelines-with-teams-toolkit-cli). *[Recommended]* -* Create CI/CD workflows. -* Customize CI/CD workflows. +* [Set up CI/CD pipelines using your own workflow](#set-up-cicd-pipelines-using-your-own-workflow). *[Optional]* -### Create CI/CD workflows +## Set up CI/CD pipelines with Teams Toolkit CLI -1. Download the corresponding template files from [Tools and Templates](#tools-and-templates). -1. Rename the downloaded template files by your needs. -1. Put them under `.github/workflows`, which is the designated folder for GitHub Actions. -1. Commit and push these template files into remote repositories. -1. Add necessary [encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) for your workflows. -1. Trigger your workflows. Check more [details](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow) about how to trigger a workflow on GitHub. --### Customize CI workflow +> [!NOTE] +> Use Teams Toolkit version 5.6.0 or a later. ++You can use [Teams Toolkit command line interface (CLI)](Teams-Toolkit-CLI.md) to set up CI/CD pipeline for your Teams app. ++### Prerequisites -To customize the CI workflow, you can do the following: +| **Item** | **Description** | +| | | +| Set up required resources for your Teams app, such as Teams app ID, bot ID, and so on. | ΓÇó Manually extract the resources from the `manifest.json` file under the `appPackage` folder. <br> ΓÇó Automatically generate to run the `Provision` command in Teams Toolkit. | +| Configure Azure resources |ΓÇó Manually prepare the resources by examining the bicep files under the `infra` folder. <br> ΓÇó Automatically prepare the resources using the `Provision` command in Teams Toolkit.| +| Ensure that you've a service principal and its access policies on resources are properly configured. Set up a service principal as follows:| ΓÇó [Create service principal using Entra portal](/entra/identity-platform/howto-create-service-principal-portal). <br> ΓÇó [Create service principal using Azure CLI](/cli/azure/azure-cli-sp-tutorial-1?tabs=bash). <br> ΓÇó The `Teamsapp` command-line interface (CLI) supports Azure login with a service principal secret. [Create a secret](/entra/identity-platform/howto-create-service-principal-portal) and save the client ID, client secret, and tenant ID of the service principal. <br> :::image type="content" source="../assets/images/teams-toolkit-v2/service-principal.png" alt-text="Screenshot shows the service principal secret.":::| ++After you've completed the prerequisites, let's set up a pipeline: -1. Change the trigger: By default, the CI workflow is triggered when a new pull request is created against `dev` branch. -1. Add scripts to build the project: By default, the `Build the project` step is commented. -1. Add scripts to run unit test: By default, the `Run unit test` step is commented. +* [Set up pipeline with GitHub](#set-up-pipeline-with-github). ++* [Set up pipeline with Azure DevOps](#set-up-pipeline-with-azure-devops). -### Customize CD workflow +### Set up pipeline with GitHub -To customize the CD workflow, you can do the following: +To set up the pipeline with GitHub, follow these steps: -1. Change the trigger: By default, the CD workflow is triggered when new commits are pushed into `main` branch. -1. Change the value of environment variable `TEAMSFX_ENV_NAME`: By default, the value is `dev`. -1. Change the value of environment variable `TEAMSFX_CLI_VERSION`: By default, the value is `2.*`. -1. Add scripts to build the project: By default, the `Build the project` step is commented. -1. Add scripts to run unit test: By default, the `Run unit test` step is commented. +1. Open Visual Studio Code. -### Customize Provision and Publish workflow +1. Create a `cd.yml` file in your project under `.github/workflows` folder and add the following code in the file: -To customize the Provision and Publish workflow, you can do the following: + ```yaml + on: + push: + branches: + - main + jobs: + build: + runs-on: ubuntu-latest + env: + TEAMSAPP_CLI_VERSION: "3.0.0" + # Add extra environment variables here so that teamsapp cli can use them. + + steps: + - name: "Checkout GitHub Action" + uses: actions/checkout@v4 + + - name: Setup Node 20.x + uses: actions/setup-node@v1 + with: + node-version: "20.x" + + - name: install cli + run: | + npm install @microsoft/teamsapp-cli@${{env.TEAMSAPP_CLI_VERSION}} + + - name: Login Azure by service principal + run: | + npx teamsapp auth login azure --username ${{vars.AZURE_SERVICE_PRINCIPAL_CLIENT_ID}} \ + --service-principal true \ + --tenant ${{vars.AZURE_TENANT_ID}} \ + --password ${{secrets.AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET }} \ + --interactive false + + - name: Deploy to hosting environment + run: | + npx teamsapp deploy --ignore-env-file true \ + --interactive false + + - name: Package app + run: | + npx teamsapp package + + - name: upload appPackage + uses: actions/upload-artifact@v4 + with: + name: artifact + path: appPackage/build/appPackage.zip + ``` ++ > [!NOTE] + > The default pipeline triggers when push events occur on the main branch. You've the option to modify it to suit your specific requirements. ++1. Go to GitHub. ++1. Update the following variables and secrets you created during the prerequisites: ++ * `AZURE_SERVICE_PRINCIPAL_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET` ++ :::image type="content" source="../assets/images/teams-toolkit-v2/repo-settings.png" alt-text="Screenshot shows the repo settings."::: ++ > [!NOTE] + > The `AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET` variable must be set as secret. + > Utilize the [GitHub environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-variables) to use different sets of variables. ++ * Go to the `teamsapp.yml` file. In the `deploy` stage, the values enclosed in `${{}}` are the required variable keys. If you've used the `provision` command from Teams Toolkit, you can locate the values in the environment files in the `.env` folder. ++ Set the `BOT_AZURE_APP_SERVICE_RESOURCE_ID` as a repository variable: -1. Change the trigger: By default, the workflow is triggered manually. -1. Change the value of environment variable `TEAMSFX_ENV_NAME`: By default, the value is `dev`. -1. Change the value of environment variable `TEAMSFX_CLI_VERSION`: By default, the value is `2.*`. + :::image type="content" source="../assets/images/teams-toolkit-v2/teamsappyml.png" alt-text="Screenshot shows the bot Azure app service resource ID in teamsapp.yml file."::: -## Set up pipelines with Azure DevOps + * Go to the `appPackage/manifest.json` file. The values enclosed in `${{}}` are the required variable keys. If you've used the `provision` command from Teams Toolkit, you can locate the values in the environment files in the `.env` folder. -To set up pipelines with Azure DevOps for CI/CD: + Set the `TEAMS_APP_ID` as a repository variable: -* Create CI/CD pipelines. -* Customize CI/CD pipelines. + :::image type="content" source="../assets/images/teams-toolkit-v2/manifest.png" alt-text="Screenshot shows the Teams app ID in manifest file."::: -### Create CI/CD pipelines +1. In the GitHub, navigate to your repositoryΓÇÖs **Settings** and select **Secrets and variables** > **Actions**. -1. Download the corresponding template files from [Tools and Templates](#tools-and-templates). -1. Rename the downloaded template files by your needs. -1. Put them under `.azure/pipelines`, which is the conventional folder for Azure Pipelines. -1. Commit and push these template files into remote repositories. -1. Create corresponding Azure DevOps pipelines by following [Create your first Azure DevOps Pipeline](/azure/devops/pipelines/create-first-pipeline). -1. Add necessary [Azure DevOps Pipeline variables](/azure/devops/pipelines/process/variables) for your pipelines. -1. 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](/azure/devops/pipelines/build/triggers). + Update the variable keys that you've gathered for the following variables: -### Customize CI pipeline + * `AZURE_SERVICE_PRINCIPAL_CLIENT_ID` + * `AZURE_TENANT_ID` + * `AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET` + * `BOT_AZURE_APP_SERVICE_RESOURCE_ID` + * `TEAMS_APP_ID` -To customize the CI pipeline, you can do the following: + Add the variables defined in your repo directly into your yml file, excluding the following three variables: -1. Change the trigger: By default, the CI pipeline is triggered when a new pull request is created against `dev` branch. -1. Add scripts to build the project: By default, the `Build the project` step is commented. -1. Add scripts to run unit test: By default, the `Run unit test` step is commented. + * `AZURE_SERVICE_PRINCIPAL_CLIENT_ID` + * `AZURE_TENANT_ID` + * `AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET` -### Customize CD pipeline + :::image type="content" source="../assets/images/teams-toolkit-v2/modification.png" alt-text="Screenshot shows the modified pipeline yml."::: -To customize the CD pipeline, you can do the following: +1. Run the pipeline. -1. Change the trigger: By default, the CD pipeline is triggered when new commits are pushed into `main` branch. -1. Change the value of environment variable `TEAMSFX_ENV_NAME`: By default, the value is `dev`. -1. Change the value of environment variable `TEAMSFX_CLI_VERSION`: By default, the value is `2.*`. -1. Add scripts to build the project: By default, the `Build the project` step is commented. -1. Add scripts to run unit test: By default, the `Run unit test` step is commented. + Push code to the repo to trigger pipeline. -### Customize Provision and Publish pipelines + > [!NOTE] + > You don't need to commit env files under env folder to the repo. The env variables required for executing the CI/CD pipeline are already set in the repo variables. -To customize the Provision and Publish pipeline, you can do the following: + After the pipeline executes successfully, the log displays that the code is deployed to Azure and the `appPackage` is generated in the artifacts. -1. Change the trigger: By default, the workflow is triggered manually. -1. Change the value of environment variable `TEAMSFX_ENV_NAME`: By default, the value is `dev`. -1. Change the value of environment variable `TEAMSFX_CLI_VERSION`: By default, the value is `2.*`. + :::image type="content" source="../assets/images/teams-toolkit-v2/artifact.png" alt-text="Screenshot shows the `appPackage` is generated in the artifacts."::: -## Set up pipelines with Jenkins +### Set up pipeline with Azure DevOps -To set up pipelines with Jenkins for CI/CD: +To set up the pipeline with Azure DevOps, follow these steps: -* Create CI/CD pipelines. -* Customize CI/CD pipelines. +1. Open Visual Studio Code. -### Create CI/CD pipelines +1. Create a `cd.yml` file in your project and add the following code in the file: -1. Download the corresponding template files from [Tools and Templates](#tools-and-templates). -1. Rename the downloaded template files by your needs. -1. Put them under `.jenkins/pipelines`, which can be a conventional folder for Jenkins Pipelines. + ```yaml + trigger: + - main + + pool: + vmImage: ubuntu-latest + + variables: + TEAMSAPP_CLI_VERSION: 3.0.0 + + steps: + - task: NodeTool@0 + inputs: + versionSpec: "20" + checkLatest: true + + - script: | + npm install @microsoft/teamsapp-cli@$(TEAMSAPP_CLI_VERSION) + displayName: "Install CLI" + + - script: | + npx teamsapp auth login azure --username $(AZURE_SERVICE_PRINCIPAL_CLIENT_ID) --service-principal true --tenant $(AZURE_TENANT_ID) --password $(AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET) --interactive false + displayName: "Login Azure by service principal" + + - script: | + npx teamsapp deploy --ignore-env-file true --interactive false + displayName: "Deploy to Azure" + workingDirectory: $(System.DefaultWorkingDirectory) + + - script: | + npx teamsapp package + displayName: "Package app" + workingDirectory: $(System.DefaultWorkingDirectory) + + - publish: $(System.DefaultWorkingDirectory)/appPackage/build/appPackage.zip + artifact: artifact + ``` -### Customize CI pipeline + > [!NOTE] + > The default pipeline triggers when push events occur on the main branch. You can modify it to meet your specific requirements. -To customize the CI pipeline, you can do the following: +1. Push the code to the repo. -1. Change the trigger: By default, the CI pipeline is triggered periodically. -1. Add scripts to build the project: By default, the `Build the project` step is commented. -1. Add scripts to run unit test: By default, the `Run unit test` step is commented. +1. Setup Azure pipeline. -### Customize CD pipeline + After you push your code to the repo, navigate to **Pipelines** and select **New pipeline**. Select your repo and the existing yml file to configure your pipeline. -To customize the CD pipeline, you can do the following: +1. Update the following variables and secrets you created during the prerequisites: -1. Change the trigger: By default, the CD pipeline is triggered periodically. -1. Change the value of environment variable `TEAMSFX_ENV_NAME`: By default, the value is `dev`. -1. Change the value of environment variable `TEAMSFX_CLI_VERSION`: By default, the value is `2.*`. -1. Add scripts to build the project: By default, the `Build the project` step is commented. -1. Add scripts to run unit test: By default, the `Run unit test` step is commented. + * `AZURE_SERVICE_PRINCIPAL_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET` -### Customize Provision and Publish pipelines + * Go to the `teamsapp.yml` file. In the `deploy` stage, the values enclosed in `${{}}` are the required variable keys. If you've used the `provision` command from Teams Toolkit, you can locate the values in the environment files in the `.env` folder. -To customize the Provision and Publish pipeline, you can do the following: + Set the `BOT_AZURE_APP_SERVICE_RESOURCE_ID` as a repository variable: -1. Change the trigger: By default, the pipeline is triggered periodically. -1. Change the value of environment variable `TEAMSFX_ENV_NAME`: By default, the value is `dev`. -1. Change the value of environment variable `TEAMSFX_CLI_VERSION`: By default, the value is `2.*`. + :::image type="content" source="../assets/images/teams-toolkit-v2/teamsappyml.png" alt-text="Screenshot shows the bot Azure app service resource ID in teamsapp.yml file."::: -## Set up pipelines for other platforms + * Go to the `appPackage/manifest.json` file. The values enclosed in `${{}}` are the required variable keys. If you've used the `provision` command from Teams Toolkit, you can locate the values in the environment files in the `.env` folder. -You can follow the predefined listed example bash scripts from [Tools and Templates](#tools-and-templates) to build and customize CI/CD pipelines on the other platforms: + Set the `TEAMS_APP_ID` as a repository variable: -The scripts are based on a cross-platform TeamsFx command line tool [TeamsFx-CLI](https://www.npmjs.com/package/@microsoft/teamsfx-cli). You can install it with `npm install -g @microsoft/teamsfx-cli` and follow the [documentation](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/cli/user-manual.md) to customize the scripts. + :::image type="content" source="../assets/images/teams-toolkit-v2/manifest.png" alt-text="Screenshot shows the Teams app ID in manifest file."::: -> [!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. + You need to set the following key name variables in the repo: -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](https://docs.github.com/en/actions/reference/encrypted-secrets). + * `AZURE_SERVICE_PRINCIPAL_CLIENT_ID` + * `AZURE_TENANT_ID` + * `AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET` + * `BOT_AZURE_APP_SERVICE_RESOURCE_ID` + * `TEAMS_APP_ID` -## How to create Azure service principals for use? + To set variables in your pipeline, go to your pipeline and select **Edit** > **Variables**. -To provision and deploy resources targeting Azure inside CI/CD, you must create an Azure service principal for use. + > [!NOTE] + > For security purposes, select the **Keep this value secret** checkbox if it's necessary. -Perform the following steps to create Azure service principals: + :::image type="content" source="../assets/images/teams-toolkit-v2/secret.png" alt-text="Screenshot shows the keep this value secret in new variable page."::: -1. Register a 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. +1. Run the pipeline. -> [!TIP] -> Save your tenant id, application id (AZURE_SERVICE_PRINCIPAL_NAME), and the secret (AZURE_SERVICE_PRINCIPAL_PASSWORD) for future use. + Push code to the repo to trigger pipeline. -For more information, see [Azure service principals guidelines](/azure/active-directory/develop/howto-create-service-principal-portal). The following are the three ways to create service principals: + > [!NOTE] + > There's no need to commit env files under env/ folder to the repo. The env variables required for executing the CI/CD pipeline are already established in the pipeline variables. -* [Microsoft Azure portal](/azure/active-directory/develop/howto-create-service-principal-portal) -* [Windows PowerShell](/azure/active-directory/develop/howto-authenticate-service-principal-powershell) -* [Microsoft Azure CLI](/cli/azure/create-an-azure-service-principal-azure-cli) + After the pipeline executes successfully, the log displays that the code is deployed to Azure and the `appPackage` is generated in the artifacts. -## Publish Teams app using Teams Developer Portal + :::image type="content" source="../assets/images/teams-toolkit-v2/published.png" alt-text="Screenshot shows the pipeline runs successfully."::: -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 use [Developer Portal for Teams](https://dev.teams.microsoft.com/home). +## Set up CI/CD pipelines using your own workflow -Perform the following steps to publish your app: +If the Teams App CLI doesn't meet your pipeline requirements, you can develop a custom deployment process that suits your needs. This section provides guidance on deploying to Azure with custom methods. -1. Sign in to [Developer portal for Teams](https://dev.teams.microsoft.com) 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**. +> [!NOTE] +> If you already have a complete CI/CD pipeline for deploying to your Azure resource, and your Teams app needs to read environment variables during runtime, configure these environment variables in the settings of your Azure resource. For post-deployment testing, see [generate Teams app package](#generate-teams-app-package). ++The `teamsapp deploy` command executes the actions defined in the `deploy` stage of the `teamsapp.yml` file. The `deploy` stage consists of `build` and `deploy` actions. To create a custom deployment method, rewrite these actions based on your specific requirements and preferences. ++As an example, a basic bot TypeScript project has the following deploy stage in its `teamsapp.yml`: ++```yaml +deploy: + # Run npm command + - uses: cli/runNpmCommand + name: install dependencies + with: + args: install + - uses: cli/runNpmCommand + name: build app + with: + args: run build --if-present + # Deploy your application to Azure App Service using the zip deploy feature. + # For additional details, refer to this link. + - uses: azureAppService/zipDeploy + with: + # Deploy base folder + artifactFolder: . + # Ignore file location, leave blank will ignore nothing + ignoreFile: .webappignore + # The resource id of the cloud resource to be deployed to. + # This key will be generated by arm/deploy action automatically. + # You can replace it with your existing Azure Resource id + # or add it to your environment variable file. + resourceId: ${{BOT_AZURE_APP_SERVICE_RESOURCE_ID}} +``` ++These actions perform the following tasks: ++* Run `npm install` and `npm build` to build the project. +* Deploy code to Azure app service. ++You can customize these actions in your CI/CD pipeline. Here's an example that utilizes GitHub's actions: ++```yaml +# build +- name: Setup Node 20.x + uses: actions/setup-node@v1 + with: + node-version: '20.x' +- name: 'npm install, build' + run: | + npm install + npm run build --if-present ++- name: 'zip artifact for deployment' + run: | + zip -r deploy.zip . --include 'node_modules/*' 'lib/*' 'web.config' ++# deploy +- name: 'Login via Azure CLI' + uses: azure/login@v1 + with: + client-id: ${{ vars.CLIENT_ID }} + tenant-id: ${{ vars.TENANT_ID }} + subscription-id: ${{ vars.SUBSCRIPTION_ID }} ++- name: 'Run Azure webapp deploy action using azure RBAC' + uses: azure/webapps-deploy@v2 + with: + app-name: ${{ vars.AZURE_WEBAPP_NAME }} + package: deploy.zip +``` ++The Teams Toolkit supports Teams app projects, written in various programming languages and designed for hosting on different Azure services. The following actions for building and deploying. Use these actions when setting CI/CD deployment pipelines. ++Build: ++| Language | GitHub | Azure Pipeline | +|||| +|JS or TS |[actions/setup-node](https://github.com/actions/setup-node) |[NodeTool@0](/azure/devops/pipelines/tasks/reference/node-tool-v0) | +|C# |[actions/setup-dotnet](https://github.com/actions/setup-dotnet) |[DotNetCoreCLI@2](/azure/devops/pipelines/tasks/reference/dotnet-core-cli-v2) | ++Deploy: ++| Resource | GitHub | Azure Pipeline | +|||| +|Azure App Service |[azure/webapps-deploy](https://github.com/Azure/webapps-deploy) |[AzureWebApp@1](/azure/devops/pipelines/tasks/reference/azure-web-app-v1) | +|Azure Functions |[Azure/functions-action](https://github.com/Azure/functions-action) |[AzureFunctionApp@2](/azure/devops/pipelines/tasks/reference/azure-function-app-v2) | +|Azure Static Web Apps |[Azure/static-web-apps-deploy](https://github.com/Azure/static-web-apps-deploy)|[AzureStaticWebApp@0](/azure/devops/pipelines/tasks/reference/azure-static-web-app-v0) | ++### Credential needed for login to Azure ++When you deploy app code to Azure App Service, Azure Functions, or Azure Container App through CI/CD, you need a service principal for Azure login. You can log in to Azure using a service principal in two ways: ++* OpenID Connect (OIDC): ++ * For GitHub action, see how to [use the Azure login action with OpenID Connect](/azure/developer/github/connect-from-azure#use-the-azure-login-action-with-openid-connect). ++ * For Azure pipeline, see how to [create an Azure Resource Manager service connection that uses workload identity federation](/azure/devops/pipelines/library/connect-to-azure#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation). ++* Secret: The TeamsApp CLI supports sign-in using a service principal with a secret. For more information, see how to [create a new client secret](/entra/identity-platform/howto-create-service-principal-portal). ++## Generate Teams app package ++To distribute your Teams app, the `appPackage` is required. You can automatically create the `appPackage.zip` using the `teamsapp package` command in `Teamsapp` CLI. If you're unable to use `Teamsapp` CLI, follow these steps to manually create the `appPackage`: ++1. Prepare a `appPackage` folder. +1. Place the `manifest.json` file in the `appPackage` folder. The default `manifest.json` file in the Teams Toolkit project contains placeholders, denoted by ${{}}. Replace these placeholders with the correct values. +1. Place your app icons in the `appPackage` folder. To prepare your app icon, see [app icons](../concepts/build-and-test/apps-package.md#app-icons). +1. Zip the files in the `appPackage` folder. ## See also |
| platform | Whats New | https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/whats-new.md | Teams platform features that are available to all app developers. **2024 April** -* ***April 12, 2024***: [Implement authentication in API-based search message extensions to provide secure and seamless access to your app.](messaging-extensions/build-api-based-message-extension.md#authentication) +* ***April 12, 2024***: [Implement authentication in API-based search message extensions to provide secure and seamless access to your app.](messaging-extensions/build-api-based-message-extension.md#authentication). * ***April 12, 2024***: [Introducing app manifest v1.17 with semanticDescription, samplePrompts, and dashboardCards](resources/schem). * ***April 12, 2024***: [Outlook extensions specifies Outlook Add-ins within an app manifest and simplify the distribution and acquisition across the Microsoft 365 ecosystem](resources/schem#extensionsrequirements). * ***April 12, 2024***: [Create Dashboardcards that can be pinned to a dashboard such as Microsoft Viva Connections to provide a summarized view of app information](resources/schem#dashboardcards). |