Configurar pipelines de CI/CD

Você pode estabelecer um pipeline de CI/CD (Integração Contínua e Implantação Contínua) para aplicativos do Microsoft Teams criados com o Microsoft 365 Agents Toolkit (anteriormente conhecido como Teams Toolkit). Um pipeline de CI/CD do aplicativo Teams consiste em três componentes:

  1. Compile o projeto.

  2. Implante o projeto nos recursos de nuvem.

  3. Gerar o pacote de aplicativos do Teams.

Observação

Para criar um pipeline para um aplicativo do Teams, você deve preparar os recursos de nuvem necessários, como o Aplicativo Web do Azure, o Azure Functions ou o Aplicativo Web Estático do Azure, e definir as configurações do aplicativo.

Para compilar o projeto, você precisa compilar o código-fonte e criar os artefatos de implantação necessários. Há dois métodos para implantar os artefatos:

Configurar pipelines de CI/CD com a CLI do Agents Toolkit

Observação

Use o Agents Toolkit versão 5.6.0 ou posterior.

Você pode usar a interface de linha de comando do Kit de Ferramentas de Agentes do Microsoft 365 para configurar um pipeline de CI/CD para seu aplicativo do Teams.

Pré-requisitos

Item Descrição
Configure os recursos necessários para seu aplicativo do Teams, como ID do aplicativo do Teams, ID do bot e assim por diante. • Extraia manualmente os manifest.json recursos do arquivo na appPackage pasta.
• Gere automaticamente executando o Provision comando no Agents Toolkit.
Configurar recursos do Azure • Prepare manualmente os recursos examinando os arquivos bicep na infra pasta.
• Prepare automaticamente os recursos usando o comando no Kit de ferramentas do Provision Teams.
Certifique-se de ter uma entidade de serviço configurada corretamente com políticas de acesso apropriadas nos recursos. A atk interface de linha de comando (CLI) dá suporte ao logon do Azure por meio de autenticação baseada em certificado ou autenticação baseada em senha (segredo do aplicativo). Você pode criar uma entidade de serviço com autenticação baseada em certificado e salvar o certificado appId gerado (ID do cliente) e tenant (ID do locatário) ou criar um segredo e salvar a ID do cliente, o segredo do cliente e a ID do locatário da entidade de serviço.
A captura de tela mostra o segredo da entidade de serviço.
Para obter mais informações sobre a entidade de serviço, consulte:
• Criar entidade de serviço usando o portal Entra.
• Criar entidade de serviço usando a CLI do Azure.

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

Configurar pipeline com o GitHub

Para configurar o pipeline com o GitHub, siga estas etapas:

  1. Abra o Visual Studio Code.

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

    on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TEAMSAPP_CLI_VERSION: "1.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/m365agentstoolkit-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 atk 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 atk deploy --ignore-env-file true \
          --interactive false

      - name: Package app
        run: |
          npx atk package

      - name: upload appPackage
        uses: actions/upload-artifact@v4
        with:
          name: artifact
          path: appPackage/build/appPackage.zip

  3. Vá para o GitHub.

  4. Atualize as seguintes variáveis e segredos que você 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 de cadeia de caracteres Base64 do certificado gerado.

      A captura de tela mostra as configurações do repositório.

      Observação

      A AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64 variável deve ser definida como secreta. Use o ambiente GitHub para diferentes conjuntos de variáveis.

    • Vá para o m365agents.yml arquivo. deploy No estágio, os valores incluídos são ${{}} as chaves de variáveis necessárias. Se você usou o provision comando do Agents Toolkit, pode localizar os valores nos arquivos de ambiente da .env pasta.

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

      A captura de tela mostra o bot Azure a ID do recurso do serviço de aplicativo em m365agents.yml arquivo.

    • Vá para o appPackage/manifest.json arquivo. Os valores incluídos são ${{}} as chaves de variáveis necessárias. Se você usou o provision comando do Agents Toolkit, pode localizar os valores nos arquivos de ambiente da .env pasta.

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

      A captura de tela mostra a ID do aplicativo Teams no arquivo de manifesto.

  5. No GitHub, navegue até Configurações do repositório e selecione Segredos e variáveis>Ações.

    Atualize as chaves de variável que você coletou 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 em seu repositório diretamente ao arquivo yml, excluindo as três variáveis a seguir:

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID

    • AZURE_TENANT_ID

    • AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET ou AZURE_SERVICE_PRINCIPAL_CERTIFICATE_BASE64

      A captura de tela mostra o yml do pipeline modificado.

  6. Execute o pipeline.

    Efetue push do código no repositório para disparar o pipeline.

    Observação

    Você não precisa confirmar arquivos env na pasta env no repositório. As variáveis env necessárias para executar o pipeline de CI/CD já estão definidas nas variáveis de repositório.

    Depois que o pipeline for executado com êxito, o log exibe que o código foi implantado no Azure e appPackage gerado nos artefatos.

    A captura de tela mostra que o 'appPackage' é gerado nos artefatos.

Tive um problema

Configurar pipeline com o DevOps do Azure

Para configurar o pipeline com o DevOps do Azure, siga estas etapas:

  1. Abra o Visual Studio Code.

  2. Crie um cd.yml arquivo em seu projeto e adicione o seguinte código ao arquivo:

    trigger:
  - main

pool:
  vmImage: ubuntu-latest

variables:
  TEAMSAPP_CLI_VERSION: 1.0.4

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

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

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

  - script: |
      npx atk 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 atk deploy --ignore-env-file true --interactive false
    displayName: "Deploy to Azure"
    workingDirectory: $(System.DefaultWorkingDirectory)

  - script: |
      npx atk package
    displayName: "Package app"
    workingDirectory: $(System.DefaultWorkingDirectory)

  - publish: $(System.DefaultWorkingDirectory)/appPackage/build/appPackage.zip
    artifact: artifact

  3. Efetue push do código para o repositório.

  4. Configure o pipeline do Azure.

    Depois de enviar seu código por push para o repositório, navegue até Pipelines e selecione Novo pipeline. Selecione o repositório e o arquivo yml existente para configurar o pipeline.

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

    • AZURE_SERVICE_PRINCIPAL_CLIENT_ID, AZURE_TENANT_ID

    • Vá para o m365agents.yml arquivo. deploy No estágio, os valores incluídos são ${{}} as chaves de variáveis necessárias. Se você usou o provision comando do Agents Toolkit, pode localizar os valores nos arquivos de ambiente da .env pasta.

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

      A captura de tela mostra o bot Azure a ID do recurso do serviço de aplicativo em m365agents.yml arquivo.

    • Vá para o appPackage/manifest.json arquivo. Os valores incluídos são ${{}} as chaves de variáveis necessárias. Se você usou o provision comando do Agents Toolkit, pode localizar os valores nos arquivos de ambiente da .env pasta.

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

      A captura de tela mostra a ID do aplicativo Teams no arquivo de manifesto.

    Você precisa 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, acesse o pipeline e selecione Editar>variáveis.

    Em seu projeto do Azure DevOps, navegue até a Biblioteca de Pipelines> e adicione um novo arquivo seguro. Carregue o arquivo de certificado (.pem) e nomeie-o como azure_sp_cert.pem.

  6. Execute o pipeline.

    Efetue push do código no repositório para disparar o pipeline.

    Observação

    Não há necessidade de enviar arquivos env na pasta env/ para o repositório. As variáveis env necessárias para executar o pipeline de CI/CD já estão estabelecidas nas variáveis de pipeline.

    Depois que o pipeline for executado com êxito, o log exibe que o código foi implantado no Azure e appPackage gerado nos artefatos.

    A captura de tela mostra que o pipeline é executado com êxito.

Tive um problema

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

Se a CLI do Agents Toolkit não atender aos requisitos de pipeline, você poderá desenvolver um processo de implantação personalizado que atenda às suas necessidades. Esta seção fornece diretrizes sobre como implantar no Azure com métodos personalizados.

Observação

Se você já tiver um pipeline de CI/CD completo para implantação no recurso do Azure e o aplicativo do Teams precisar ler variáveis de ambiente durante o runtime, configure essas variáveis de ambiente nas configurações do recurso do Azure. Para testes pós-implantação, consulte gerar pacote de aplicativos do Teams.

O atk deploy comando executa as ações definidas no deploy estágio do m365agents.yml arquivo. O deploy estágio consiste em build e deploy ações. Para criar um método de implantação personalizado, reescreva essas ações com base em seus requisitos e preferências específicos.

Por exemplo, um projeto TypeScript de bot básico tem o seguinte estágio de implantação em seu m365agents.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}}

Essas ações realizam as seguintes tarefas:

  • Execute npm install e npm build compile o projeto.
  • Implante o código no serviço de aplicativo do Azure.

Você pode personalizar essas ações em seu pipeline de CI/CD. Aqui está 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 Kit de Ferramentas de Agentes dá suporte a projetos de aplicativo do Teams, escritos em várias linguagens de programação e projetados para hospedagem em diferentes serviços do Azure. As ações a seguir para compilar e implantar. Use essas ações ao configurar pipelines de implantação de CI/CD.

Build:

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

Implantar:

Recurso GitHub Pipeline do Azure
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

Credencial necessária para entrar no Azure

Ao implantar o código do aplicativo no Serviço de Aplicativo do Azure, no Azure Functions ou no Aplicativo de Contêiner do Azure por meio de CI/CD, você precisa de uma entidade de serviço para logon do Azure. Você pode fazer logon no Azure usando uma entidade de serviço de duas maneiras:

Tive um problema

Gerar pacote de aplicativos do Teams

Para publicar seu aplicativo do Teams, o appPackage é necessário. Você pode criar automaticamente o appPackage.zip usando o atk package comando na atk CLI. Se você não conseguir usar atk a CLI, siga estas etapas para criar manualmente o appPackage:

  1. Prepare uma appPackage pasta.
  2. Coloque o manifest.jsonappPackage arquivo na pasta. O arquivo padrão manifest.json no projeto Agents Toolkit contém espaços reservados, indicados por ${{}}. Substitua esses espaços reservados pelos valores corretos.
  3. Coloque os ícones de appPackage aplicativo na pasta. Para preparar o ícone do aplicativo, consulte Ícones de aplicativo.
  4. Compacte os appPackage arquivos na pasta.

Confira também

  • Last updated on