Compartilhar via

Configurar pipelines de CI/CD

  • Artigo

Pode configurar um pipeline de Integração Contínua e Implementação Contínua (CI/CD) para aplicações do Microsoft Teams criadas com o Teams Toolkit. Um pipeline CI/CD da aplicação Teams consiste em três partes:

  1. Compile o projeto.

  2. Implementar o projeto em recursos da cloud.

  3. Gerar pacote de aplicações do Teams.

Observação

Para criar um pipeline para uma aplicação do Teams, é necessário preparar os recursos da cloud necessários, como a Aplicação Web do Azure, Azure Functions ou a Aplicação Web Estática do Azure, e configurar as definições da aplicação.

Para criar o projeto, tem de compilar o código fonte e criar os artefactos de implementação necessários. Existem dois métodos para implementar os artefactos:

Configurar pipelines CI/CD com a CLI do Teams Toolkit

Observação

Utilize o Teams Toolkit versão 5.6.0 ou posterior.

Pode utilizar a interface de linha de comandos (CLI) do Teams Toolkit para configurar o pipeline CI/CD para a sua aplicação Teams.

Pré-requisitos

Item Descrição
Configure os recursos necessários para a sua aplicação Teams, como o ID da aplicação Teams, o ID do bot, etc. • Extraia manualmente os recursos do manifest.json ficheiro sob a appPackage pasta .
• Gerar automaticamente para executar o Provision comando no Teams Toolkit.
Configurar recursos do Azure • Prepare manualmente os recursos ao examinar os ficheiros bíceps na infra pasta .
• Prepare automaticamente os recursos com o Provision comando no Teams Toolkit.
Certifique-se de que tem um principal de serviço configurado corretamente com políticas de acesso adequadas nos recursos. A Teamsapp interface de linha de comandos (CLI) suporta o início de sessão do Azure através da autenticação baseada em certificado ou da autenticação baseada em palavra-passe (segredo da aplicação). Pode criar um principal de serviço com autenticação baseada em certificado e guardar o certificado gerado( appId ID de cliente) e tenant (ID do inquilino) ou criar um segredo e guardar o ID de cliente, o segredo do cliente e o ID de inquilino do principal de serviço.
Captura de ecrã a mostrar o segredo do principal de serviço.
Para obter mais informações sobre o principal de serviço, veja:
• Crie um principal de serviço com o portal Entra.
• Criar principal de serviço com a CLI do Azure.

Depois de concluir os pré-requisitos, vamos configurar um pipeline:

Configurar o pipeline com o GitHub

Para configurar o pipeline com o GitHub, siga estes passos:

  1. Abra o Visual Studio Code.

  2. Crie um cd.yml ficheiro no seu projeto .github/workflows na pasta e adicione o seguinte código no ficheiro:

    on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TEAMSAPP_CLI_VERSION: "3.0.4"
      # 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: Retrieve the secret and decode it to a file
        env:
          CERTIFICATE_BASE64: ${{ secrets.AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64 }}
        run: |
          echo $CERTIFICATE_BASE64 | base64 --decode > cert.pem

      - 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 cert.pem \
          --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

  3. Aceda ao GitHub.

  4. Atualize as seguintes variáveis e segredos que criou durante os pré-requisitos:

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID, AZURE_TENANT_IDe AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64. AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64 é o conteúdo codificado da cadeia Base64 do certificado que gerou.

      Captura de ecrã a mostrar as definições do repositório.

      Observação

      A AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64 variável tem de ser definida como secreta. Utilize o ambiente do GitHub para diferentes conjuntos de variáveis.

    • Aceda ao teamsapp.yml ficheiro. deploy Na fase, os valores incluídos são ${{}} as chaves variáveis necessárias. Se tiver utilizado o provision comando do Teams Toolkit, pode localizar os valores nos ficheiros de ambiente na .env pasta.

      Defina como BOT_AZURE_APP_SERVICE_RESOURCE_ID uma variável de repositório:

      Captura de ecrã a mostrar o ID de recurso do serviço de aplicações do Azure no ficheiro teamsapp.yml.

    • Aceda ao appPackage/manifest.json ficheiro. Os valores incluídos são ${{}} as chaves variáveis necessárias. Se tiver utilizado o provision comando do Teams Toolkit, pode localizar os valores nos ficheiros de ambiente na .env pasta.

      Defina como TEAMS_APP_ID uma variável de repositório:

      Captura de ecrã a mostrar o ID da aplicação Teams no ficheiro de manifesto.

  5. No GitHub, navegue para as Definições do seu repositório e selecione Segredos e variáveis Ações>.

    Atualize as chaves variáveis que recolheu para as seguintes variáveis:

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID
    • AZURE_TENANT_ID
    • AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET ou AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64
    • BOT_AZURE_APP_SERVICE_RESOURCE_ID
    • TEAMS_APP_ID

    Adicione as variáveis definidas no seu repositório diretamente ao ficheiro yml, excluindo as três variáveis seguintes:

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID

    • AZURE_TENANT_ID

    • AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET ou AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64

      Captura de ecrã a mostrar o yml do pipeline modificado.

  6. Execute o pipeline.

    Envie código para o repositório para acionar o pipeline.

    Observação

    Não precisa de consolidar ficheiros env na pasta env para o repositório. As variáveis env necessárias para executar o pipeline CI/CD já estão definidas nas variáveis de repositório.

    Depois de o pipeline ser executado com êxito, o registo mostra que o código é implementado no Azure e o appPackage é gerado nos artefactos.

    Captura de ecrã a mostrar que

Configurar o pipeline com o Azure DevOps

Para configurar o pipeline com o Azure DevOps, siga estes passos:

  1. Abra o Visual Studio Code.

  2. Crie um cd.yml ficheiro no seu projeto e adicione o seguinte código no ficheiro:

    trigger:
  - main

pool:
  vmImage: ubuntu-latest

variables:
  TEAMSAPP_CLI_VERSION: 3.0.4

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: "20"
      checkLatest: true

  - script: |
      npm install @microsoft/teamsapp-cli@$(TEAMSAPP_CLI_VERSION)
    displayName: "Install CLI"

  - task: DownloadSecureFile@1  
    name: certFile  
    displayName: 'Download Certificate File'  
    inputs:  
      secureFile: 'azure_sp_cert.pem' 

  - script: |
      npx teamsapp auth login azure --username $(AZURE_SERVICE_PRINCIPAL_CLIENT_ID) --service-principal true --tenant $(AZURE_TENANT_ID) --password $(certFile.secureFilePath) --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

  3. Envie o código para o repositório.

  4. Configurar o pipeline do Azure.

    Depois de emitir o código para o repositório, navegue para Pipelines e selecione Novo pipeline. Selecione o seu repositório e o ficheiro yml existente para configurar o pipeline.

  5. Atualize as seguintes variáveis e defina o certificado que criou durante os pré-requisitos:

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID, AZURE_TENANT_ID

    • Aceda ao teamsapp.yml ficheiro. deploy Na fase, os valores incluídos são ${{}} as chaves variáveis necessárias. Se tiver utilizado o provision comando do Teams Toolkit, pode localizar os valores nos ficheiros de ambiente na .env pasta.

      Defina como BOT_AZURE_APP_SERVICE_RESOURCE_ID uma variável de repositório:

      Captura de ecrã a mostrar o ID de recurso do serviço de aplicações do Azure no ficheiro teamsapp.yml.

    • Aceda ao appPackage/manifest.json ficheiro. Os valores incluídos são ${{}} as chaves variáveis necessárias. Se tiver utilizado o provision comando do Teams Toolkit, pode localizar os valores nos ficheiros de ambiente na .env pasta.

      Defina como TEAMS_APP_ID uma variável de repositório:

      Captura de ecrã a mostrar o ID da aplicação Teams no ficheiro de manifesto.

    Tem de definir as seguintes variáveis de nome de chave no repositório:

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID
    • AZURE_TENANT_ID
    • BOT_AZURE_APP_SERVICE_RESOURCE_ID
    • TEAMS_APP_ID

    Para definir variáveis no pipeline, aceda ao pipeline e selecione Editar>Variáveis.

    No projeto do Azure DevOps, navegue paraa Biblioteca de Pipelines> e adicione um novo ficheiro seguro. Carregue o ficheiro de certificado (.pem) e atribua o nome .azure_sp_cert.pem

  6. Execute o pipeline.

    Envie código para o repositório para acionar o pipeline.

    Observação

    Não é necessário consolidar ficheiros env na pasta env/ para o repositório. As variáveis env necessárias para executar o pipeline CI/CD já estão estabelecidas nas variáveis de pipeline.

    Depois de o pipeline ser executado com êxito, o registo mostra que o código é implementado no Azure e o appPackage é gerado nos artefactos.

    Captura de ecrã a mostrar que o pipeline é executado com êxito.

Configurar pipelines CI/CD com o seu próprio fluxo de trabalho

Se a CLI da Aplicação Teams não cumprir os seus requisitos de pipeline, pode desenvolver um processo de implementação personalizado que se adeque às suas necessidades. Esta secção fornece orientações sobre a implementação no Azure com métodos personalizados.

Observação

Se já tiver um pipeline CI/CD completo para implementar no recurso do Azure e a sua aplicação do Teams precisar de ler variáveis de ambiente durante o runtime, configure estas variáveis de ambiente nas definições do recurso do Azure. Para testes pós-implementação, veja Gerar pacote de aplicações do Teams.

O teamsapp deploy comando executa as ações definidas na deploy fase do teamsapp.yml ficheiro. A deploy fase consiste em build e deploy ações. Para criar um método de implementação personalizado, reescreva estas ações com base nos seus requisitos e preferências específicos.

Por exemplo, um projeto TypeScript de bot básico tem a seguinte fase de implementação no respetivo teamsapp.yml:

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}}

Estas ações executam as seguintes tarefas:

  • Execute npm install e npm build para criar o projeto.
  • Implementar código no serviço de aplicações do Azure.

Pode personalizar estas ações no pipeline CI/CD. Eis um exemplo que utiliza as ações do GitHub:

# 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

O Teams Toolkit suporta projetos de aplicações do Teams, escritos em várias linguagens de programação e concebidos para alojamento em diferentes serviços do Azure. As seguintes ações para criar e implementar. Utilize estas ações ao definir pipelines de implementação CI/CD.

Build:

Idioma GitHub Azure Pipeline
JS ou TS actions/setup-node NodeTool@0
C# actions/setup-dotnet DotNetCoreCLI@2

Implantar:

Recurso GitHub Azure Pipeline
Serviço do Aplicativo do Azure azure/webapps-deploy AzureWebApp@1
Azure Functions Azure/functions-action AzureFunctionApp@2
Aplicativos Web Estáticos do Azure Azure/static-web-apps-deploy AzureStaticWebApp@0

Credenciais necessárias para iniciar sessão no Azure

Quando implementa o código da aplicação para Serviço de Aplicativo do Azure, Azure Functions ou Azure Container App através de CI/CD, precisa de um principal de serviço para o início de sessão do Azure. Pode iniciar sessão no Azure com um principal de serviço de duas formas:

Gerar pacote de aplicações do Teams

Para publicar a sua aplicação Teams, é appPackage necessário. Pode criar automaticamente o com o appPackage.zipteamsapp package comando na Teamsapp CLI. Se não conseguir utilizar Teamsapp a CLI, siga estes passos para criar manualmente o appPackage:

  1. Preparar uma appPackage pasta.
  2. Coloque o manifest.json ficheiro na appPackage pasta . O ficheiro predefinido manifest.json no projeto Teams Toolkit contém marcadores de posição, indicados por ${{}}. Substitua estes marcadores de posição pelos valores corretos.
  3. Coloque os ícones da aplicação na appPackage pasta . Para preparar o ícone da aplicação, veja ícones da aplicação.
  4. Zipe os ficheiros na appPackage pasta .

Confira também