Publicar uma ação personalizada do GitHub

  • 6 minutos

Aqui, você aprenderá sobre como escolher a visibilidade certa para sua ação, práticas recomendadas para documentar e controlar o controle de versão de sua ação e como publicá-la no GitHub Marketplace.

Escolha um local para a sua ação

Diagrama que exibe as duas opções de visibilidade para uma ação: pública ou privada.

Ao criar uma ação, é importante primeiro decidir onde você quer que a ação viva e a visibilidade dessa ação, se será public ou private. A visibilidade da ação determina quais recomendações e requisitos são necessários para liberar essa ação. Vamos dar uma olhada mais de perto nessas duas opções de visibilidade.

Público

Os fluxos de trabalho em qualquer repositório podem usar ações públicas. Se você estiver desenvolvendo uma ação com a intenção de torná-la de código aberto ou disponibilizá-la publicamente por meio do GitHub Marketplace, recomendamos (e, na maioria dos casos, é necessário) que a ação tenha seu próprio repositório em vez de agrupá-la com outro código de aplicativo. Isso permite que você versione, rastreie e libere a ação como qualquer outro software. Isso torna mais fácil para a comunidade do GitHub descobrir a ação, reduz o escopo da base de código para desenvolvedores corrigirem problemas e estenderem a ação e separa o versionamento da ação do versionamento de outro código de aplicativo.

Privado

Quando uma ação está em um repositório privado, somente fluxos de trabalho no mesmo repositório podem usá-la. Com ações privadas, você pode armazenar os arquivos da ação em qualquer local do repositório. Se você planeja combinar ação, fluxo de trabalho e código de aplicativo em um único repositório, recomendamos armazenar a .github ação no diretório. Por exemplo, .github/actions/action-a e .github/actions/action-b.

Documente a sua ação

Pode ser muito frustrante usar uma nova ferramenta ou aplicativo quando a documentação é vaga ou até mesmo falta. É importante incluir uma boa documentação na sua ação para que outras pessoas possam ver como ela funciona, se você planeja torná-la pública ou privada. A primeira coisa a fazer é criar um bom README.md arquivo para sua ação.

O README.md arquivo geralmente é o primeiro lugar que os desenvolvedores olham para ver como a ação funciona. Este é um ótimo lugar para incluir todas as informações importantes para a ação. Segue-se uma lista não exaustiva de coisas a incluir:

  • Uma descrição pormenorizada da ação
  • Argumentos de entrada e saída necessários
  • Argumentos de entrada e saída opcionais
  • Segredos que a ação usa
  • Variáveis de ambiente que a ação usa
  • Um exemplo de como usar sua ação em um fluxo de trabalho

Como regra geral, o arquivo deve incluir tudo o README.md que um usuário deve saber para usar a ação. Se você acha que pode ser uma informação útil, inclua-a README.mdno .

Libere e faça a versão da sua ação

Se você estiver desenvolvendo uma ação para outras pessoas usarem, seja ela pública ou privada, você deve definir uma estratégia de gerenciamento de versão para controlar como as atualizações são distribuídas. As principais atualizações de versão, incluindo correções críticas necessárias e patches de segurança que afetam a compatibilidade, precisam ser documentadas claramente.

Boas práticas para gerenciamento de versões e versões

Uma boa estratégia de gerenciamento de versões deve incluir recomendações de controle de versão. Os usuários não devem fazer referência à ramificação padrão de uma ação com a ação, porque a ramificação padrão provavelmente conterá o código mais recente (que pode ou não ser estável) e pode resultar na quebra do fluxo de trabalho. Em vez disso, recomendamos que os usuários especifiquem uma versão principal ao usar a ação e só os direcionem para uma versão mais específica se encontrarem problemas. Eles podem fazer isso configurando seu fluxo de trabalho de Ações do GitHub para direcionar uma tag, um SHA de confirmação ou uma ramificação específica nomeada para uma versão. Vamos dar uma olhada mais de perto nessas opções de lançamento.

Etiquetas

As tags podem ser uma boa maneira de gerenciar lançamentos para uma ação. Usando tags, os usuários podem facilmente distinguir entre versões principais e secundárias. Segue-se uma lista de práticas úteis a considerar ao criar versões:

  • Crie e valide uma versão em uma ramificação de versão (como release/v1) antes de criar a tag de versão (por exemplo, v1.0.2).
  • Use o controle de versão semântico.
  • Mova a tag da versão principal (como v1, v2) para apontar para a ref do Git da versão atual.
  • Introduza uma nova tag de versão principal (v2) para alterações que interromperão os fluxos de trabalho existentes.
  • Lançar versões principais com uma tag beta para indicar seu status; por exemplo, v2-beta. Você pode remover a -beta tag quando a versão estiver pronta.

Aqui estão alguns exemplos de cada opção.

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

Use um commit's SHA

As tags são úteis e amplamente utilizadas, mas uma desvantagem de usar tags é que elas podem ser excluídas ou movidas. Com o Git, cada confirmação recebe um valor SHA calculado, que é exclusivo e não pode ser modificado. Usar um SHA de confirmação para controle de versão lhe dará a maneira mais confiável e segura de fazer a versão e usar uma ação. No entanto, muitas vezes no Git você pode abreviar o hash SHA para os primeiros vários caracteres, e o Git reconhecerá a referência. Se você estiver usando o commit's SHA para gerenciamento de liberação, precisará usar o valor SHA completo e não o valor abreviado.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Publicar uma ação no GitHub Marketplace

Renderização que diz GitHub Marketplace, ferramentas para desenvolver e melhorar seu fluxo de trabalho.

Quando estiver pronto para compartilhar sua ação com a comunidade do GitHub, você poderá publicá-la no GitHub Marketplace e alcançar milhões de usuários do GitHub. As ações publicadas no GitHub Marketplace são publicadas imediatamente se todos os requisitos forem atendidos. As ações que não atendem aos requisitos precisam ser revisadas pelo GitHub antes de serem publicadas. Você precisará garantir que o repositório inclua apenas o arquivo de metadados, o código e os arquivos necessários para a ação. A criação de um único repositório para a ação permite marcar, liberar e empacotar o código em uma única unidade. O GitHub também usa os metadados da ação na sua página do GitHub Marketplace.

A seguir estão os requisitos para publicar uma ação no GitHub Marketplace. Eles se aplicam a ações baseadas em contêiner do Docker e ações baseadas em JavaScript:

  • A ação deve estar em um repositório público.
  • Cada repositório deve conter uma única ação.
  • O arquivo de metadados da ação (action.yml ou action.yaml) deve estar no diretório raiz do repositório.
  • O name arquivo de metadados da ação deve ser exclusivo no GitHub Marketplace.
    • O nome não pode corresponder a um usuário ou organização no GitHub, a menos que o usuário ou proprietário da organização esteja publicando a ação. Por exemplo, somente a organização do GitHub pode publicar uma ação chamada github.
    • O name não pode corresponder a uma categoria existente do GitHub Marketplace.
    • O name não pode corresponder a um recurso existente do GitHub.

Você pode adicionar a ação que criou ao GitHub Marketplace marcando-a como uma nova versão e publicando-a. Existem algumas etapas guiadas no GitHub que permitem que você publique uma versão da sua ação. Você pode encontrar mais informações sobre essas etapas na seção Resumo no final deste módulo.