Publicar e instalar um pacote no GitHub Actions

Sobre GitHub Packages com GitHub Actions

O GitHub Actions ajuda você a automatizar seus fluxos de trabalho de desenvolvimento de software no mesmo lugar que você armazena o código e colabora em pull requests e problemas. Você pode escrever tarefas individuais, chamadas de ações e combiná-las para criar um fluxo de trabalho personalizado. Com o GitHub Actions, você pode criar recursos completos de integração contínua (CI, Continuous Integration) e implantação contínua (CD, Continuous Deployment) diretamente no seu repositório. Para obter mais informações, confira "Sobre o GitHub Actions".

Você pode estender os recursos de CI e CD do seu repositório publicando ou instalando pacotes como parte do seu fluxo de trabalho.

Autenticação para registros de pacotes com permissões granulares

Alguns registros do GitHub Packages dão suporte a permissões granulares. Isso significa que você pode optar por permitir que os pacotes sejam de propriedade de um usuário ou organização ou vinculados a um repositório. Para obter a lista de registros que oferecem suporte a permissões granulares, consulte "Sobre permissões para GitHub Packages."

Para registros que oferecem suporte a permissões granulares, se o seu fluxo de trabalho estiver usando um personal access token para autenticar em um registro, recomendamos fortemente que você atualize seu fluxo de trabalho para usar GITHUB_TOKEN. Para obter diretrizes sobre como atualizar seus fluxos de trabalho que se autenticam em um registro com um personal access token, confira "Como fazer upgrade de um fluxo de trabalho que acessa um registro usando um personal access token".

Para obter mais informações sobre o GITHUB_TOKEN, confira "Autenticação em um fluxo de trabalho". Para obter mais informações sobre as melhores práticas ao usar um registro em ações, confira "Proteção de segurança para GitHub Actions".

Autenticação para registros de pacotes com permissões no escopo do repositório

Alguns registros do GitHub Packages suportam apenas permissões com escopo de repositório e não suporta permissões granulares. Para obter uma lista desses registros, confira "Sobre permissões para GitHub Packages".

Se você deseja que seu fluxo de trabalho acesse um registro GitHub Packages que não suporta permissões granulares, então recomendamos usar oGITHUB_TOKEN que o GitHub cria automaticamente para seu repositório quando você habilita o GitHub Actions. Você deve definir as permissões desse token de acesso no arquivo de fluxo de trabalho para permitir acesso de leitura ao escopo contents e acesso de gravação ao escopo packages. Para forks, o GITHUB_TOKEN recebe acesso de leitura no repositório pai. Para obter mais informações, confira "Como se autenticar com o GITHUB_TOKEN".

Você pode referenciar o GITHUB_TOKEN no arquivo de fluxo de trabalho usando o contexto {{secrets.GITHUB_TOKEN}}. Para obter mais informações, confira "Como se autenticar com o GITHUB_TOKEN".

Sobre permissões e acesso a pacotes

Pacotes com escopo para usuários ou organizações

Os registros que dão suporte a permissões granulares permitem que os usuários criem e administrem pacotes como recursos autônomos no nível da organização. Os pacotes podem pertencer a uma conta pessoal ou organização e você pode personalizar o acesso a cada um dos seus pacotes separadamente das permissões de repositório.

Todos os fluxos de trabalho que acessam registros que dão suporte a permissões granulares devem usar o GITHUB_TOKEN em vez de um personal access token. Para obter mais informações sobre as melhores práticas de segurança, confira "Proteção de segurança do GitHub Actions".

Pacotes com escopo para repositórios

Quando você habilita o GitHub Actions, o GitHub instala um aplicativo GitHub no repositório. O segredo GITHUB_TOKEN é um token de acesso de instalação do Aplicativo do GitHub. Você pode usar o token de acesso de instalação para efetuar a autenticação em nome do aplicativo GitHub instalado no seu repositório. As permissões do token são restritas ao repositório do fluxo de trabalho. Para obter mais informações, confira "Permissões para o GITHUB_TOKEN".

O GitHub Packages permite que você efetue push e pull de pacotes por meio do GITHUB_TOKEN disponível para um fluxo de trabalho do GitHub Actions.

Configurações padrão de permissões e acesso para contêineres modificados por meio de fluxos de trabalho

Ao criar, instalar, modificar ou excluir um contêiner por meio de um fluxo de trabalho, existem algumas configurações padrão de permissão e acesso para garantir que os administradores tenham acesso ao fluxo de trabalho. Você também pode ajustar estas configurações de acesso.

Por exemplo, por padrão, se um fluxo de trabalho criar um contêiner usando o GITHUB_TOKEN:

O contêiner herdará o modelo de visibilidade e permissões do repositório onde o fluxo de trabalho é executado.
Os administradores do repositório onde o fluxo de trabalho é executado tornam-se os administradores do contêiner depois que o contêiner é criado.

Estes são outros exemplos de como as permissões padrão funcionam para fluxos de trabalho que gerenciam pacotes.

Tarefa de fluxo de trabalho de GitHub Actions	Acesso e permissões padrão
Faça o download de um contêiner existente	- Se o contêiner for público, qualquer fluxo de trabalho em execução em qualquer repositório poderá fazer o download do container. – Se o contêiner for interno, todos os fluxos de trabalho em execução em qualquer repositório pertencente à conta corporativa poderão baixar o contêiner. Para as organizações corporativas, você pode ler qualquer repositório na empresa – Se o contêiner for privado, somente os fluxos de trabalho em execução em repositórios que recebem permissão de leitura nesse contêiner poderão baixar o contêiner.
Faça o upload de uma nova versão para um contêiner existente	- Se o contêiner for privado, interno ou público, somente fluxos de trabalho executados em repositórios que recebem permissões de gravação nesse contêiner podem fazer o upload de novas versões para o container.
Excluir um contêiner ou versões de um contêiner	- Se o recipiente for privado, interno ou público, somente fluxos de trabalho executados em repositórios que recebem permissão de exclusão pode excluir versões existentes do container.

Você também pode ajustar o acesso a contêineres de uma forma mais granular ou ajustar alguns dos comportamentos padrão de permissões. Para obter mais informações, confira "Como configurar o controle de acesso e a visibilidade de um pacote".

Publicar um pacote usando uma ação

Você pode usar GitHub Actions para publicar automaticamente pacotes como parte do fluxo de integração contínua (CI). Esta abordagem da implantação contínua (CD) permite que você automatize a criação de novas versões do pacote, se o código atender aos seus padrões de qualidade. Por exemplo, você pode criar um fluxo de trabalho que executa testes CI toda vez que um desenvolvedor faz push do código para um branch específico. Se os testes passarem, o fluxo de trabalho poderá publicar uma nova versão do pacote em GitHub Packages.

As etapas de configuração variam de acordo com o cliente do pacote. Para obter informações gerais sobre como configurar um fluxo de trabalho para GitHub Actions, confira "Configurar um fluxo de trabalho".

O exemplo a seguir demonstra como você pode usar GitHub Actions para criar seu aplicativo e, em seguida, criar automaticamente uma imagem Docker e publicá-la em GitHub Packages.

Crie um arquivo de fluxo de trabalho no seu repositório (como .github/workflows/deploy-image.yml) e adicione o seguinte YAML:

YAML

# <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>São fornecidas por terceiros e regidas por
# <a name="separate-terms-of-service-privacy-policy-and-support"></a>termos de serviço, política de privacidade e suporte separados
# <a name="documentation"></a>online.

# <a name="github-recommends-pinning-actions-to-a-commit-sha"></a>O GitHub recomenda fixar ações em um SHA de commit.
# <a name="to-get-a-newer-version-you-will-need-to-update-the-sha"></a>Para obter uma versão mais recente, você precisará atualizar o SHA.
# <a name="you-can-also-reference-a-tag-or-branch-but-the-action-may-change-without-warning"></a>Você também pode fazer referência a uma marca ou branch, mas a ação pode ser alterada sem aviso.

name: Create and publish a Docker image

on:
 push:
   branches: ['release']

env:
 REGISTRY: ghcr.io
 IMAGE_NAME: ${{ github.repository }}

jobs:
 build-and-push-image:
   runs-on: ubuntu-latest
   permissions:
     contents: read
     packages: write

   steps:
     - name: Checkout repository
       uses: actions/checkout@v3

     - name: Log in to the Container registry
       uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
       with:
         registry: ${{ env.REGISTRY }}
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}

     - name: Extract metadata (tags, labels) for Docker
       id: meta
       uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
       with:
         images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

     - name: Build and push Docker image
       uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
       with:
         context: .
         push: true
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}

As configurações relevantes são explicadas na seguinte tabela. Para obter detalhes completos sobre cada elemento de um fluxo de trabalho, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

```yaml on: push: branches: ['release'] ```	Configura o fluxo de trabalho `Create and publish a Docker image` para que ele seja executado sempre que uma alteração é enviada por push ao branch chamado `release`.
`env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }}`	Define duas variáveis de ambiente personalizadas para o fluxo de trabalho. Estes são usados para o domínio de Container registry e um nome para a imagem Docker que esta fluxo de trabalho cria.
`jobs: build-and-push-image: runs-on: ubuntu-latest`	Há um único trabalho neste fluxo de trabalho. Ele está configurado para ser executado na última versão disponível do Ubuntu.
```yaml permissions: contents: read packages: write ```	Define as permissões concedidas ao `GITHUB_TOKEN` para as ações nesse trabalho.
```yaml - name: Log in to the Container registry uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} ```	Cria uma etapa chamada `Log in to the Container registry`, que faz logon no registro usando a conta e a senha que publicarão os pacotes. Uma vez publicados, os pacotes pertencem à conta definida aqui.
```yaml - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} ```	Esta etapa usa `docker/metadata-action` para extrair marcas e rótulos que serão aplicados à imagem especificada. A `id` "meta" permite que a saída desta etapa seja referenciada em uma etapa seguinte. O valor `images` fornece o nome base para as marcas e os rótulos.
```yaml - name: Build and push Docker image ```	Cria uma etapa chamada `Build and push Docker image`. Essa etapa é executada como parte do trabalho `build-and-push-image`.
```yaml uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc ```	Usa a ação `build-push-action` do Docker para compilar a imagem, com base no `Dockerfile` do repositório. Se a criação for bem-sucedida, ela faz p push da imagem para GitHub Packages.
```yaml with: ```	Envia os parâmetros obrigatórios para a ação `build-push-action`. Estas são definidas nas linhas subsequentes.
```yaml context: . ```	Define o contexto da criação como o conjunto de arquivos localizados no caminho especificado. Para obter mais informações, confira "Uso".
```yaml push: true ```	Faz push desta imagem para o registro se for construída com sucesso.
`tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }}`	Adiciona as tags e etiquetas extraídos na etapa "meta".

Este novo fluxo de trabalho será executado automaticamente sempre que você efetuar push de uma alteração em um branch chamado release no repositório. Veja o progresso na guia Ações.

Alguns minutos após a conclusão do fluxo de trabalho, o novo pacote ficará visível no seu repositório. Para encontrar seus pacotes disponíveis, confira "Como ver os pacotes de um repositório".

Instalar um pacote usando uma ação

Você pode instalar pacotes como parte de seu fluxo de CI usando o GitHub Actions. Por exemplo, você poderia configurar um fluxo de trabalho para que sempre que um desenvolvedor fizesse push do código para um pull request, o fluxo de trabalho resolveria as dependências, fazendo o download e instalando pacotes hospedados pelo GitHub Packages. Em seguida, o fluxo de trabalho pode executar testes de CI que exigem as dependências.

A instalação de pacotes hospedados pelo GitHub Packages por meio do GitHub Actions exige uma configuração mínima ou uma autenticação adicional quando você usa o GITHUB_TOKEN. A transferência de dados também é gratuita quando uma ação instala um pacote. Para obter mais informações, confira "Sobre a cobrança do GitHub Packages".

As etapas de configuração variam de acordo com o cliente do pacote. Para obter informações gerais sobre como configurar um fluxo de trabalho para GitHub Actions, confira "Configurar um fluxo de trabalho".

Como atualizar um fluxo de trabalho que acessa um registro usando um personal access token

GitHub Packages oferece suporte ao GITHUB_TOKEN para autenticação fácil e segura em seus fluxos de trabalho. Se você estiver usando um registro que oferece suporte a permissões granulares e seu fluxo de trabalho estiver usando um personal access token para autenticar no registro, recomendamos que você atualize seu fluxo de trabalho para usar o GITHUB_TOKEN.

Para obter mais informações sobre o GITHUB_TOKEN, confira "Autenticação em um fluxo de trabalho".

O uso do GITHUB_TOKEN em vez de um personal access token (classic) com o escopo do repo aumenta a segurança do repositório, pois você não precisa usar um personal access token de longa duração que oferece acesso desnecessário ao repositório em que o fluxo de trabalho é executado. Para obter mais informações sobre as melhores práticas de segurança, confira "Proteção de segurança do GitHub Actions".

Acesse a página inicial do seu pacote.
Na barra lateral esquerda, clique em Acesso ao Actions.
Para garantir que seu pacote de contêiner tenha acesso ao seu fluxo de trabalho, você deve adicionar o repositório em que o fluxo de trabalho é armazenado no contêiner. Clique em Adicionar repositório e pesquise o repositório que deseja adicionar.

Observação: a adição de um repositório ao seu contêiner por meio da opção de menu Acesso ao Actions é diferente da conexão do seu contêiner a um repositório. Para obter mais informações, confira "Como garantir o acesso de fluxo de trabalho ao seu pacote" e "Como conectar um repositório a um pacote".
Opcionalmente, usando o menu suspenso "função", selecione o nível de acesso padrão que você gostaria que o repositório tivesse na imagem do seu contêiner.
Abra o arquivo do seu fluxo de trabalho. Na linha onde você faz login no registro, substitua seu personal access token com ${{ secrets.GITHUB_TOKEN }}.

Por exemplo, esse fluxo de trabalho publica uma imagem do Docker no Container registry e usa ${{ secrets.GITHUB_TOKEN }} para se autenticar.