Implemente para o Funções do Azure usando o GitHub Actions

Pode usar um fluxo de trabalho do GitHub Actions para compilar e implementar automaticamente o código da sua função no Azure com o Azure/functions-action.

Para implementar utilizando o GitHub Actions, complete estes três passos principais:

  1. Crie uma identidade gerida atribuída pelo utilizador no Azure com uma credencial federada que confie no seu repositório GitHub, e atribua-lhe o papel de Contribuidor do Website na sua aplicação funcional.
  2. Adicione o ID do cliente, o ID do tenant e o ID da subscrição da identidade como segredos do repositório no GitHub.
  3. Adicione um ficheiro YAML de fluxo de trabalho ao seu repositório que utilize azure/login com OpenID Connect (OIDC) para se autenticar e, em seguida, chame Azure/functions-action para implementar.

Quando utiliza o portal Azure para ativar o GitHub Actions, o Functions executa automaticamente estas tarefas, tanto na sua subscrição do Azure como no seu repositório GitHub.

Crie uma configuração de fluxo de trabalho para o Funções do Azure

Manténs um ficheiro YAML (.yml) que define a configuração do fluxo de trabalho no /.github/workflows/ caminho do teu repositório. Esta definição contém as ações e parâmetros que compõem o fluxo de trabalho, que é específico para a linguagem de desenvolvimento de suas funções.

Escolha um método para criar o seu ficheiro de fluxo de trabalho usando o seletor no topo do artigo:

Método Melhor para Suporte OIDC
Modelo de fluxo de trabalho Controlo total: copiar um template pronto para OIDC e personalizá-lo Requer configuração
portal do Azure Configuração mais simples: o portal pode criar a identidade, credenciais e ficheiro de fluxo de trabalho por si Configurado para ti
Marketplace do GitHub GitHub-first: comece pelos templates integrados do marketplace do GitHub Requer configuração e modificação de modelos

Descrição geral da autenticação

O GitHub Actions deve autenticar-se com o Azure para implementar o seu código. Este artigo utiliza o OpenID Connect (OIDC), que é o método de autenticação recomendado. O OIDC utiliza credenciais federadas para criar uma relação de confiança entre o seu repositório GitHub e uma identidade gerida atribuída pelo utilizador no Microsoft Entra. Nenhum segredo está guardado no GitHub.

Exemplo de autenticação OIDC

O seguinte exemplo inline mostra o padrão central de autenticação e implementação OIDC usado em todos os modelos de workflow:

permissions:
  id-token: write
  contents: read

steps:
  - name: 'Login via OIDC'
    uses: azure/login@v3
    with:
      client-id: ${{ secrets.AZURE_CLIENT_ID }}
      tenant-id: ${{ secrets.AZURE_TENANT_ID }}
      subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

  - name: 'Deploy to Azure Functions'
    uses: Azure/functions-action@v1
    with:
      app-name: ${{ env.AZURE_FUNCTIONAPP_NAME }}
      package: ${{ env.AZURE_FUNCTIONAPP_PACKAGE_PATH }}

Considerações de autenticação OIDC no GitHub Actions

  • O OIDC utiliza federação de identidade de carga de trabalho e apenas suporta identidades geridas atribuídas pelo utilizador.
  • Quando ativas uma implementação baseada no GitHub Actions no portal Azure, a autenticação OIDC é usada por defeito.
  • Com o OIDC, o ID do cliente, o ID do tenant e o ID de subscrição da identidade gerida são armazenados como segredos do repositório GitHub.
  • Use o controlo de acesso baseado em papéis do Azure (Azure RBAC) para limitar o acesso apenas aos recursos do Azure necessários para a sua implementação.

Pré-requisitos

  • Uma conta no Azure com uma subscrição ativa. Crie uma conta gratuitamente.

  • Uma conta no GitHub. Se não tiver uma, inscreva-se gratuitamente.

  • Código-fonte do Project num repositório GitHub.

  • Uma compreensão básica dos fluxos de trabalho do GitHub Actions. Se és novo no GitHub Actions, consulta Compreender o GitHub Actions.

  • Uma aplicação de funções funcional alojada no Azure (apenas código ou baseada em contentores).

  • (Apenas implantações de contentores) Um registo de contentores existente, como o Azure Container Registry.

  • CLI do Azure, quando se desenvolve localmente. Também pode usar a CLI do Azure no Azure Cloud Shell.

Crie uma identidade gerida para a implementação do GitHub Actions

O OpenID Connect (OIDC) é o método de autenticação recomendado para implementações do GitHub Actions no Funções do Azure. Com o OIDC, configura uma identidade gerida atribuída pelo utilizador no Azure e cria uma relação de confiança com o seu repositório GitHub. O fluxo de trabalho pode então autenticar-se com o Azure sem guardar credenciais como segredos.

  1. Use o comando az identity create para criar uma identidade gerenciada atribuída pelo usuário:

    az identity create --name myGitHubDeployIdentity --resource-group <RESOURCE_GROUP> \
--query "{clientId: clientId, tenantId: tenantId}" -o table

    Substitua <RESOURCE_GROUP> pelo nome do seu grupo de recursos.

  2. A partir da saída, tome nota dos valores clientId e tenantId. Também obtenha o seu ID de subscrição:

    az account show --query "{subId: id}" -o table

    Precisas destes três valores mais tarde, quando adicionares credenciais ao GitHub.

  3. Utilize o comando az role assignment create para atribuir a função Website Contributor à identidade gerida, no âmbito da sua aplicação de funções:

    IDENTITY_PRINCIPAL=$(az identity show --name myGitHubDeployIdentity --resource-group <RESOURCE_GROUP> --query 'principalId' -o tsv)
FUNCTION_APP_ID=$(az functionapp show --name <APP_NAME> --resource-group <RESOURCE_GROUP> --query 'id' -o tsv)
az role assignment create --assignee $IDENTITY_PRINCIPAL --role "Website Contributor" --scope $FUNCTION_APP_ID

    Substitua <APP_NAME> e <RESOURCE_GROUP> pelos nomes da sua aplicação e do grupo de recursos, respetivamente.

  4. Use o comando az identity federated-credential create para criar uma credencial federada que confia em tokens do seu repositório do GitHub:

    az identity federated-credential create \
    --identity-name myGitHubDeployIdentity \
    --resource-group <RESOURCE_GROUP> \
    --name github-deploy-credential \
    --issuer https://token.actions.githubusercontent.com \
    --subject repo:<GITHUB_ORG>/<REPO_NAME>:ref:refs/heads/<BRANCH_NAME> \
    --audiences api://AzureADTokenExchange

    Substitua <RESOURCE_GROUP>, <GITHUB_ORG>, <REPO_NAME>, e <BRANCH_NAME> pelos seus valores. O assunto deve corresponder à ramificação que aciona o fluxo de trabalho.

  5. (Opcional) Se estiver a implementar um contentor do Azure Container Registry, atribua também o acrpull papel à identidade gerida:

    IDENTITY_PRINCIPAL=$(az identity show --name myGitHubDeployIdentity --resource-group <RESOURCE_GROUP> --query 'principalId' -o tsv)
az role assignment create --assignee $IDENTITY_PRINCIPAL --role acrpull \
    --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerRegistry/registries/<REGISTRY_NAME>

    Substitua <SUBSCRIPTION_ID>, <RESOURCE_GROUP> e <REGISTRY_NAME> pelos teus valores.

Adicionar credenciais ao GitHub

Use os valores que copiou quando criou a identidade gerida.

  1. Em GitHub, vai ao teu repositório.

  2. Vai a Definições>Segredos e variáveis>Ações.

  3. No separador Segredos , selecione Novo segredo de repositório.

  4. Crie cada um dos seguintes segredos:

    Name Value
    AZURE_CLIENT_ID A clientId da identidade gerida
    AZURE_TENANT_ID O tenantId da identidade gerida
    AZURE_SUBSCRIPTION_ID O ID de subscrição que contém a tua aplicação de funções

Para implementações de contentores provenientes de um registo privado, também são necessários segredos específicos do registo. Para mais informações, consulte Ação de Login no Docker.

Criar o fluxo de trabalho a partir de um modelo

A melhor maneira de criar manualmente uma configuração de fluxo de trabalho é começar a partir do modelo oficialmente suportado.

  1. Escolha Windows ou Linux para garantir que obtém o modelo para o sistema operativo correto.

    Implementações para Windows usam runs-on: windows-latest. Implementações containerizadas requerem Linux.

  2. Utilize o modelo de fluxo de trabalho OIDC específico da linguagem do repositório de ações do Funções do Azure. Copie o conteúdo completo do ficheiro para um novo ficheiro nomeado .github/workflows/deploy-function-app.yml no seu repositório:

    name: Build and deploy .NET project to Azure Function App using OIDC

on:
  push:
    branches: [ main ]
  workflow_dispatch:

env:
  AZURE_FUNCTIONAPP_NAME: 'APP_NAME'         # Set this to your function app name on Azure 
  AZURE_FUNCTIONAPP_PROJECT_PATH: '.'        # Set this to the path to your function app project, defaults to the repository root. The deploy action will package the contents of this path.
  DOTNET_VERSION: '10.0.x'                   # Set this to the .NET version of your project
  BUILD_ARTIFACT_NAME: 'released-package'    # Set this according to your team's naming convention
  
jobs:
  build:
    runs-on: windows-latest # Assumes your target function app is Windows-based
    permissions:
      id-token: write  # Required for OIDC
      contents: read   # Required for actions/checkout
    defaults:
      run:
        shell: bash
        working-directory: ${{ env.AZURE_FUNCTIONAPP_PROJECT_PATH }}
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v6

      - name: 'Set up .NET version: ${{ env.DOTNET_VERSION }}'
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}

      # Perform additional steps such as running tests, if needed

      - name: 'Build and prepare .NET project for deployment'
        run: dotnet publish --configuration Release --output ./output

      - name: Upload artifact for the deployment job
        uses: actions/upload-artifact@v7
        with:
          name: ${{ env.BUILD_ARTIFACT_NAME }}
          path: ${{ env.AZURE_FUNCTIONAPP_PROJECT_PATH }}/output
          include-hidden-files: true  # Required for .NET projects
  
  deploy:
    runs-on: windows-latest # Assumes your target function app is Windows-based
    needs: build
    permissions:
      id-token: write  # Required for OIDC
    steps:
      - name: 'Download artifact from build job'
        uses: actions/download-artifact@v8
        with:
          name: ${{ env.BUILD_ARTIFACT_NAME }}
          path: '${{ env.AZURE_FUNCTIONAPP_PROJECT_PATH }}/downloaded-artifact'
     
      - name: 'Log in to Azure with AZ CLI'
        uses: azure/login@v3
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
        
      - name: 'Run the Azure Functions action'
        uses: Azure/functions-action@v1
        id: deploy-to-function-app
        with:
          app-name: ${{ env.AZURE_FUNCTIONAPP_NAME }}
          package: '${{ env.AZURE_FUNCTIONAPP_PROJECT_PATH }}/downloaded-artifact'

  3. No modelo, atualize as env: variáveis do seu projeto. Cada modelo requer AZURE_FUNCTIONAPP_NAME. As outras variáveis dependem da tua linguagem:

    Variável Required Description
    AZURE_FUNCTIONAPP_NAME Yes O nome da sua aplicação de funções no Azure
    DOTNET_VERSION Yes A versão .NET do seu projeto (por exemplo, 10.0.x)
    AZURE_FUNCTIONAPP_PROJECT_PATH No Caminho para a pasta do teu projeto. Padrão: . (raiz do repositório)

  4. Os modelos OIDC já incluem o azure/login passo com autenticação OIDC. Verifique se as referências secrets.AZURE_CLIENT_ID, secrets.AZURE_TENANT_ID e secrets.AZURE_SUBSCRIPTION_ID correspondem aos segredos do repositório que criou.

  5. Adicione este novo ficheiro YAML no caminho /.github/workflows/ do seu repositório.

Criar a configuração do fluxo de trabalho no portal

Quando usas o portal para ativar o GitHub Actions, o Functions trata de toda a configuração automaticamente. Não precisa de criar manualmente uma identidade gerida, configurar credenciais ou escrever um ficheiro de workflow. A Functions realiza estas tarefas por si:

Na sua subscrição do Azure:

  • Cria uma identidade gerida atribuída pelo utilizador e atribui-lhe o papel de Contribuidor do Website na tua aplicação de funções.
  • Adiciona uma credencial federada à identidade gerida para autenticação OIDC do GitHub.

No teu repositório GitHub:

  • Adiciona os valores do ID do cliente, ID da subscrição e ID do tenant como segredos do GitHub Actions.
  • Cria um ficheiro de fluxo de trabalho com base na pilha da sua aplicação e regista-o em .github/workflows.

Durante a criação do aplicativo de função

Podes começar rapidamente com o GitHub Actions através do separador Deployment quando crias uma função no portal do Azure. Para adicionar um fluxo de trabalho GitHub Actions quando crias uma nova aplicação funcional:

  1. No portal Azure, selecione Implementação no fluxo de Criar Aplicação de Função.

  2. Ativa Continuous Deployment se quiseres que cada atualização de código desencadeie um push de código para Azure portal.

  3. Nas definições do GitHub, selecione Autorizar para ligar a sua conta no GitHub. Inicie sessão com a conta do GitHub que tem permissão de escrita no seu repositório.

  4. Introduza a sua organização, repositório e branch do GitHub.

  5. Opcionalmente, selecione Ficheiro de Pré-visualização para ver como o ficheiro de workflow se apresenta antes de ser gerado e adicionado ao seu repositório.

  6. Conclua a configuração do seu aplicativo de função. O seu repositório de GitHub inclui agora um novo ficheiro de workflow em /.github/workflows/.

Para um aplicativo de função existente

Para adicionar um fluxo de trabalho GitHub Actions a uma aplicação de funções existente:

  1. Aceda à sua aplicação de funções no portal do Azure e selecione Implementação>Centro de Implementação.

  2. Selecione Implementação Contínua (CI/CD). Em Source, selecione GitHub. Se não vires a mensagem predefinida Building with GitHub Actions, seleciona Alterar fornecedor, escolhe GitHub Actions e seleciona OK.

  3. Se ainda não autorizou o acesso ao GitHub, selecione Autorizar. Forneça as suas credenciais de GitHub e selecione Iniciar sessão. Para autorizar uma conta GitHub diferente, selecione Alterar Conta e inicie sessão com outra conta.

  4. Selecione o seu GitHub Organization, Repository e Branch. Para implementar com o GitHub Actions, tem de ter permissões de escrita neste repositório.

  5. Para a opção de fluxo de trabalho, selecione Adicionar um fluxo de trabalho. Esta opção cria um novo ficheiro de workflow em /.github/workflows/. Para usar um fluxo de trabalho existente, selecione Usar fluxo de trabalho disponível e escolha o seu ficheiro de workflow.

  6. Nas definições de Autenticação, escolha Identidade atribuída pelo utilizador para usar o OpenID Connect (OIDC), o que é recomendado porque não exige que armazene segredos no GitHub. Selecione a sua subscrição e o nome de identidade (Novo) sugerido. É criada uma nova identidade gerida atribuída pelo utilizador, que recebe acesso ao papel de Contribuidor do Website . Se utilizar uma identidade existente, tem primeiro de lhe atribuir a função Contribuidor do Website.

    Importante

    Quando seleciona Autenticação Básica, o seu perfil de publicação, que contém segredos partilhados, é armazenado no GitHub Secrets. Deve também ativar a autenticação SCM básica, o que torna a sua aplicação menos segura.

  7. Seleciona Preview file para ver o ficheiro de workflow que é adicionado ao teu repositório de GitHub em .github/workflows/.

  8. Selecione Salvar para adicionar o arquivo de fluxo de trabalho ao repositório. Selecione o separador Registos para ver o estado das implementações atuais e anteriores.

Criar o arquivo de configuração do fluxo de trabalho

Podes criar o ficheiro de configuração do fluxo de trabalho GitHub Actions a partir dos templates do Funções do Azure diretamente a partir do teu repositório GitHub.

  1. Em GitHub, vai ao teu repositório.

  2. Selecione Ações e Novo fluxo de trabalho.

  3. Pesquise funções.

    Captura de ecrã de pesquisa por modelos de funções do GitHub Actions.

  4. Nos fluxos de trabalho da aplicação de funções apresentados criados por Microsoft Azure, encontre aquele que corresponde à sua linguagem de código e selecione Configure.

  5. No ficheiro YAML recém-criado, atualize o parâmetro env.AZURE_FUNCTIONAPP_NAME com o nome do recurso da sua aplicação de função em Azure. Também pode precisar de atualizar o parâmetro que define a versão da linguagem usada pela sua aplicação, como DOTNET_VERSION para C# ou PYTHON_VERSION aplicações Python.

  6. Os modelos predefinidos podem usar autenticação por perfil de publicação em vez da OIDC recomendada. Para mudar para OIDC e alinhar com os comportamentos do portal, faça as seguintes alterações:

    • Remova os publish-profileparâmetros , scm-do-build-during-deployment, e enable-oryx-build de Azure/functions-action.

    • Remova a definição environment da tarefa (se existir), uma vez que o sujeito da credencial federada tem de corresponder ao acionador da ramificação.

    • Adicione um azure/login passo antes do Azure/functions-action passo:

      - name: 'Login via OIDC'
  uses: azure/login@v3
  with:
    client-id: ${{ secrets.AZURE_CLIENT_ID }}
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

- name: 'Run Azure Functions Action'
  uses: Azure/functions-action@v1
  with:
    app-name: ${{ env.AZURE_FUNCTIONAPP_NAME }}
    package: ${{ env.AZURE_FUNCTIONAPP_PACKAGE_PATH }}

    • Adicione as seguintes permissões ao trabalho:

      permissions:
  id-token: write
  contents: read

  7. Verifique se o novo ficheiro de fluxo de trabalho está guardado com um nome adequado em /.github/workflows/ e selecione Submeter alterações.

Funções do Azure ação

A ação Funções do Azure (Azure/functions-action) define como o seu código é publicado para uma aplicação de funções existente em Azure, ou para um slot específico na sua aplicação.

Parâmetros

A tabela seguinte descreve os parâmetros de entrada suportados por Azure/functions-action:

Parâmetro Description
nome do aplicativo (Obrigatório) O nome da tua aplicação de funções no Azure.
embalagem (Obrigatório) O caminho para o seu projeto de publicação. Padrão: . (todos os ficheiros no repositório).
Construção remota Defina como true para solicitar uma compilação remota ao implementar numa aplicação com o plano Flex Consumption. A compilação remota utiliza sempre o Oryx. Não definas também scm-do-build-during-deployment ou enable-oryx-build. Padrão: false.
scm-do-build-during-deployment Permitir que o site Kudu execute operações de pré-implementação, como compilações remotas. Defina para true que o Kudu construa o seu projeto durante a implementação. Padrão: false. Para obter mais informações, veja SCM_DO_BUILD_DURING_DEPLOYMENT.
enable-oryx-build Permitir que o Kudu resolva dependências de projetos usando o Oryx. Defina isto e o scm-do-build-during-deployment para true usar o Oryx em vez do fluxo de trabalho. Padrão: false. Apenas Linux.
nome-do-slot A ranhura de implementação onde implementar. Predefinição: slot de produção.
publicar-perfil O nome do segredo do GitHub que contém o teu perfil de publicação. Não é necessário ao usar a autenticação OIDC recomendada.
SKU Defina como flexconsumption ao autenticar com publish-profile num plano Flex Consumption. Não é necessário com autenticação OIDC ou outros planos de alojamento.
respect-pom-xml (Apenas Java) Defina true para obter o artefacto de implantação a partir do pom.xml. Quando true, defina o pacote para .. Padrão: false.
respect-funcignore Defina como true para respeitar o ficheiro .funcignore e excluir os caminhos indicados. Padrão: false.

A tabela seguinte mostra quais os parâmetros suportados para cada plano de alojamento:

Parâmetro Consumo Flexível Elástico Premium Dedicado Consumo
nome do aplicativo Required Required Required Required
embalagem Required Required Required Required
Construção remota Optional — — —
scm-do-build-during-deployment — Optional Optional Optional
enable-oryx-build — Opcional (Linux) Opcional (Linux) Opcional (Linux)
nome da ranhura Não suportado Optional Optional Optional
publicar-perfil Não recomendado Não recomendado Não recomendado Não recomendado
SKU Apenas publicar perfil — — —
respect-pom-xml Opcional (Java) Opcional (Java) Opcional (Java) Opcional (Java)
respect-funcignore Optional Optional Optional Optional

Métodos de implantação

Quando usa o GitHub Actions, o método de implementação depende do seu plano de alojamento:

Plano de alojamento Método de implantação
Consumo Flexível Implantação de pacotes
Elástico Premium Implementação do ZIP
Dedicado (Serviço de Aplicativo) Implementação do ZIP
Consumo Windows: implementação ZIP
Linux: URL do pacote externo*

* A capacidade de executar seus aplicativos no Linux em um plano de consumo está planejada para a aposentadoria. Para mais informações, consulte o Plano de Consumo para Alojamento do Funções do Azure.

Para mais informações, consulte Tecnologias de implementação em Funções do Azure.

Próximos passos

  • Last updated on