Como gerenciar ações personalizadas

Saiba como criar e gerenciar suas próprias ações, e personalize ações compartilhadas pela comunidade do GitHub.

Neste artigo

Definir o local da ação

Se você estiver desenvolvendo uma ação a ser usada por outras pessoas, recomendamos manter a ação no próprio repositório em vez de criar um pacote dela com outro código de aplicativo. Assim, você poderá controlar as versões e monitorar a ação como qualquer outro software.

Para compartilhar ações na empresa sem publicá-las publicamente, armazene as ações em um repositório interno e configure o repositório para permitir o acesso aos fluxos de trabalho do GitHub Actions em outros repositórios pertencentes à mesma organização ou a outras organizações da empresa. Para saber mais, confira Compartilhando ações e fluxos de trabalho com sua empresa.

Você pode armazenar os arquivos de ação em qualquer local do seu repositório. Se você pretende combinar a ação, o fluxo de trabalho e o código do aplicativo em um só repositório, recomendamos armazenar a ação no diretório .github. Por exemplo, .github/actions/action-a e .github/actions/action-b.

Como garantir a compatibilidade com outras plataformas

Muitas pessoas acessam o GitHub em um domínio diferente do GitHub.com, como o GHE.com ou em um domínio personalizado do GitHub Enterprise Server.

Para garantir que a sua ação seja compatível com outras plataformas, não use referências embutidas em código para URLs de API, como https://api.github.com. Em vez disso, você pode:

  • Usar variáveis de ambiente (confira Referência de variáveis):

    • Para a API REST, use a variável de ambiente GITHUB_API_URL.
    • Para o GraphQL, use a variável de ambiente GITHUB_GRAPHQL_URL.

  • Usar um kit de ferramentas, como @actions/github, que possa definir automaticamente as URLs corretas.

Usando gerenciamento de versão em ações

Esta seção explica como você pode usar o gerenciamento de versões para distribuir atualizações nas suas ações de forma previsível.

Práticas recomendadas para gerenciamento de versões

Se você estiver desenvolvendo uma ação para outras pessoas usarem, recomendamos que você use o gerenciamento de versão para controlar como você distribui as atualizações. Os usuários podem esperar que a versão de patch de uma ação inclua os pachtes de segurança e as correções críticas necessárias, mas permaneça compatível com os fluxos de trabalho existentes. Você deve considerar lançar uma nova versão principal sempre que as suas alterações afetarem a compatibilidade.

Nessa abordagem de gerenciamento de versão, os usuários não devem fazer referência ao branch-padrão da ação, uma vez que é provável que contenha o último código e, consequentemente, pode ser instável. Em vez disso, você pode recomendar que os usuários especifiquem uma versão principal ao usar a sua ação e direcioná-los para uma versão mais específica somente se encontrarem problemas.

Para usar uma versão de ação específica, os usuários podem configurar seu fluxo de trabalhoGitHub Actions para atingir uma tag, um SHA do commit ou um branch nomeado para uma versão.

Usar tags para o gerenciamento de versão

Recomendamos o uso de tags para gerenciamento da versão de ações. Ao usar essa abordagem, os seus usuários poderão distinguir facilmente as versões principais e não principais:

  • Crie e valide uma versão em uma ramificação de versão (como release/v1) antes de criar a marcação de versão (por exemplo, v1.0.2).
  • Criar uma versão usando uma versão semântica. Para saber mais, confira Gerenciar versões em repositórios.
  • Mova a marcação de versão principal (como v1, v2) a fim de apontar para a referência do Git da versão atual. Para saber mais, confira Noções básicas do Git – Marcação.
  • Introduza uma nova marca de versão principal (v2) para alterações que interromperão os fluxos de trabalho existentes. Por exemplo, mudar as entradas de uma ação seria uma alteração relevante.
  • As versões principais podem ser lançadas inicialmente com uma tag beta para indicar o status, por exemplo, v2-beta. Em seguida, a tag -beta poderá ser removida quando estiver pronta.

Este exemplo demonstra como um usuário pode fazer referência a uma tag da versão principal:

steps:
    - uses: actions/javascript-action@v1

Este exemplo demonstra como um usuário pode fazer referência a uma tag da versão do patch:

steps:
    - uses: actions/javascript-action@v1.0.1

Usar branches para gerenciamento de versão

Se você preferir usar nomes de branch para gerenciamento de versão, este exemplo irá demonstrar como fazer referência a um branch nomeado:

steps:
    - uses: actions/javascript-action@v1-beta

Usar um SHA do commit para o gerenciamento de versão

Cada commit do Git recebe um valor SHA calculado, que é único e imutável. Os usuários da sua ação podem preferir depender de um valor SHA do commit, uma vez que esta abordagem pode ser mais confiável do que especificar uma tag, que pode ser excluída ou movida. No entanto, isso significa que os usuários não receberão mais atualizações realizadas na ação. Você deve usar o valor SHA completo de um commit e não um valor abreviado.

steps:
    - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Criar um arquivo README para a ação

Se você planeja compartilhar sua ação publicamente, é recomendável criar um arquivo README para ajudar as pessoas a saberem como usar a ação. Você pode incluir estas informações no README.md:

  • Descrição detalhada do que a ação faz;
  • Argumentos obrigatórios de entrada e saída;
  • Argumentos opcionais de entrada e saída;
  • Segredos usados pela ação;
  • Variáveis de ambiente usadas pela ação;
  • Um exemplo de uso da ação no fluxo de trabalho.