Publicar uma ação personalizada do GitHub

Concluído

Aqui, você aprenderá a escolher a visibilidade certa para sua ação, as melhores práticas para documentação e controle de versão de sua ação e como publicar a ação no Marketplace do GitHub.

Escolher um local para a ação

Ao criar uma ação, é importante decidir primeiro onde você deseja que essa ação seja ativada 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 examinar mais detalhadamente essas duas opções de visibilidade.

Público

Fluxos de trabalho em qualquer repositório podem usar ações públicas. Se você estiver desenvolvendo uma ação com intenção de torná-la software livre ou disponibilizá-la publicamente por meio do Marketplace do GitHub, recomendamos (e na maioria dos casos é obrigatório) que a ação tenha o próprio repositório em vez de ser agrupada com outro código de aplicativo. Isso permite o controle de versão, o acompanhamento e a liberação da ação, assim como qualquer outra parte de software. Isso torna mais fácil para a comunidade do GitHub descobrir a ação, restringe o escopo da base de código para desenvolvedores que estejam corrigindo problemas e estendendo a ação e separa o controle de versão da ação do controle de versão de outro código do aplicativo.

Privados

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

Documentar a ação

Pode ser muito frustrante usar uma nova ferramenta ou aplicativo quando não existe documentação ou ela é vaga. É importante incluir uma boa documentação com a ação para que outras pessoas possam ver como ela funciona, independentemente de você planejar deixá-la pública ou privada. A primeira coisa a fazer é criar um arquivo README.md válido para sua ação.

O arquivo README.md é geralmente o primeiro item que os desenvolvedores examinarão para ver como a ação funciona. Esse é um ótimo lugar para incluir todas as informações importantes sobre a ação. Veja abaixo uma lista não exaustiva de coisas a serem incluídas:

• 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.

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

Liberar e controlar a versão da ação

Se você estiver desenvolvendo uma ação para outras pessoas usarem, independentemente de ser pública ou privada, defina 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 estar claramente documentadas.

Boas práticas para o gerenciamento de versão

Uma boa estratégia de gerenciamento de versão 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 tendo a ação como a ramificação padrão, pois ele provavelmente contém o código mais recente (que pode ou não ser estável) e isso pode resultar na interrupção do fluxo de trabalho. Em vez disso, recomendamos que os usuários especifiquem uma versão principal ao usar a ação e só sejam direcionados para uma versão mais específica se encontrarem problemas. Eles podem fazer isso configurando o fluxo de trabalho do GitHub Actions para visar uma marca, um SHA de confirmação ou uma ramificação específica nomeada para uma versão. Vamos examinar essas opções de versão com mais detalhes.

Marcações

As marcações podem ser uma boa maneira de gerenciar versões de uma ação. Usando marcações, os usuários podem facilmente distinguir entre as versões principal e secundária. Abaixo, temos uma lista de práticas úteis a serem consideradas na criação de versões:

• 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).
• Use o controle de versão semântico.
• 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.
• Introduza uma nova marca de versão principal (v2) para alterações que interromperão os fluxos de trabalho existentes.
• Libere versões principais com uma marcação beta para indicar seu status, por exemplo, v2-beta. Você poderá remover a marcação -beta 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

Usar o SHA de confirmação

As marcações são úteis e amplamente usadas, mas uma desvantagem de usar marcações é que elas podem ser excluídas ou movidas. Com o Git, cada confirmação recebe um valor de SHA calculado, que é exclusivo e não pode ser modificado. O uso de um SHA de confirmação para controle de versão fornecerá a maneira mais confiável e segura de controlar a versão e o uso de uma ação. No entanto, no Git é comum que você possa abreviar o hash de SHA com os primeiros caracteres e o Git reconheça a referência. Se estiver usando o SHA de confirmação para gerenciamento de versão, você precisará usar o valor de SHA completo e não o valor abreviado.

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

Publicar uma ação no Marketplace do GitHub

Quando já puder compartilhar sua ação com a comunidade do GitHub, você poderá publicá-la no Marketplace do GitHub e alcançar milhões de usuários do GitHub. As ações publicadas no Marketplace do GitHub são publicadas imediatamente quando todos os requisitos são atendidos. Ações que não atenderem aos requisitos precisarão ser revisadas pelo GitHub antes de serem publicadas. Você precisa ter certeza de que o repositório inclui apenas o arquivo de metadados, o código e os arquivos necessários para a ação. Criar um repositório único para a ação permite que você identifique, lance e empacote o código em uma única unidade. O GitHub também usa os metadados da ação em sua página do Marketplace do GitHub.

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

• A ação precisa estar em um repositório público.
• Cada repositório precisa conter uma única ação.
• O arquivo de metadados da ação (action.yml ou action.yaml) precisa estar no diretório raiz do repositório.
• O name no arquivo de metadados da ação precisa ser exclusivo no Marketplace do GitHub.
  • 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 GitHub pode publicar uma ação chamada github.
  • O name não pode corresponder a uma categoria existente do Marketplace do GitHub.
  • O name não pode corresponder a um recurso existente do GitHub.

Você pode adicionar a ação criada ao Marketplace do GitHub marcando-a como uma nova versão e, em seguida, publicando-a. Há algumas etapas guiadas no GitHub que permitem que você publique uma versão da ação. Encontre mais informações sobre essas etapas na seção de Resumo no final deste módulo.