Publicar e instalar um pacote no GitHub Actions

Sobre GitHub Package Registry 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, consulte "Sobre 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.

Efetuar a autenticação no Container registry

Para efetuar a autenticação em Container registry dentro de um fluxo de trabalho GitHub Actions, use o GITHUB_TOKEN para obter a melhor segurança e experiência. If your workflow is using a personal access token (PAT) to authenticate to ghcr.io, then we highly recommend you update your workflow to use the GITHUB_TOKEN.

For guidance on updating your workflows that authenticate to ghcr.io with a personal access token, see "Upgrading a workflow that accesses ghcr.io."

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

Se você estiver usando Container registry em ações, siga nossas práticas recomendadas em matéria de segurança naEnrijecimento de segurança para o GitHub Actions".

Efetuar a autenticação nos registros do pacote em GitHub

Se você quiser que o seu fluxo de trabalho seja autenticado em GitHub Package Registry para acessar o registro de um pacote diferente de Container registry em GitHub.com, , recomendamos o uso de GITHUB_TOKEN que GitHub cria automaticamente para o seu repositório quando você habilita GitHub Actions em vez de um token de acesso pessoal para autenticação. Você deverá definir as permissões para este token de acesso no arquivo do fluxo de trabalho para conceder acesso de leitura para o conteúdo escopo e acesso de gravação para o escopo pacotes. Para bifurcações, o GITHUB_TOKEN recebe acesso de leitura para o repositório principal. Para obter mais informações, consulte "Autenticação com o GITHUB_TOKEN".

Você pode fazer referência ao GITHUB_TOKEN no seu arquivo de fluxo de trabalho usando o contexto {{secrets.GITHUB_TOKEN}}. Para obter mais informações, consulte "Permissões para o GITHUB_TOKEN".

Sobre permissões e acesso de pacote para pacotes pertencentes ao repositório

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 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, consulte "Permissões para o GITHUB_TOKEN".

GitHub Package Registry permite que você faça push e pull de pacotes por meio do GITHUB_TOKEN disponível para um fluxo de trabalho de GitHub Actions.

Sobre permissões e acesso de pacote para Container registry

O Container registry (ghcr.io) permite aos usuários criar e administrar contêineres como recursos independentes no nível da organização. Os contêineres podem pertencer a uma conta pessoal ou organização e você pode personalizar o acesso a cada um dos seus contêineres separadamente das permissões de repositório.

Todos os workflows que acessam o Container registry devem usar o GITHUB_TOKEN em vez de um token de acesso pessoal. Para obter mais informações sobre as melhores práticas de segurança, consulte "Enrijecimento de segurança para o 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 cria 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.

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, consulte "Configurar o controle de acesso e 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 Package Registry.

As etapas de configuração variam de acordo com o cliente do pacote. Para obter informações gerais sobre a configuração de um fluxo de trabalho para GitHub Actions, consulte "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 Package Registry.

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

# This workflow uses actions that are not certified by GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# documentação.

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 em um fluxo de trabalho, consulte "sintaxe de fluxo de trabalho para GitHub Actions".

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 

- 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 }}

Este novo fluxo de trabalho será executado automaticamente toda vez que você fizer uma alteração em uma versão nomeada do branch no repositório. Você pode visualizar o progresso na aba 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, consulte "Visualizar 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 Package Registry. Em seguida, o fluxo de trabalho pode executar testes de CI que exigem as dependências.

A instalação de pacotes hospedados pelo GitHub Package Registry através 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, consulte "Sobre a cobrança do GitHub Package Registry".

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

Atualizando um fluxo de trabalho que acessa ghcr.io

O Container registry é compatível com GITHUB_TOKEN para autenticação fácil e segura nos seus fluxos de trabalho. Se seu fluxo de trabalho estiver usando um token de acesso pessoal (PAT) para efetuar a autenticação com ghcr.io, é altamente recomendável atualizar o seu fluxo de trabalho para usar o GITHUB_TOKEN.

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

O uso do GITHUB_TOKEN em vez de um PAT, que inclui o escopo do repositório aumenta a segurança do repositório, pois você não precisa usar um PAT de longa duração que oferece acesso desnecessário ao repositório em que o seu fluxo de trabalho é executado. Para obter mais informações sobre as melhores práticas de segurança, consulte "Enrijecimento de segurança para o GitHub Actions".

1. Acesse a página inicial do seu pacote.

2. Na barra lateral esquerda, clique em Acesso às ações.

3. 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 Adicionar repositório e pesquise o repositório que deseja adicionar.

   Observação: Adicionar um repositório ao seu contêiner por meio da opção de menu Acesso às ações é diferente de conectar seu contêiner a um repositório. Para obter mais informações, consulte "Garantir o acesso ao fluxo de trabalho para o seu pacote" "Conectar um repositório a um pacote".

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

5. Abra o arquivo do seu fluxo de trabalho. Na linha em que você efetua o login em ghcr.io, substitua seu PAT por ${{ secrets.GITHUB_TOKEN }}.

Por exemplo, este fluxo de trabalho publica um imagem do Docker usando ${{ secrets.GITHUB_TOKEN }} para efetuar a autenticação.

name: Demo Push

on:   
  push:
    # Publish `master` as Docker `latest` image.
    branches:
      - master
      - seed

    # Publish `v1.2.3` tags as releases.
    tags:
      - v*

  # Run tests for any PRs.
  pull_request:

env:
  IMAGE_NAME: ghtoken_product_demo

jobs:
  # Push image to GitHub Packages.
  # See also https://docs.docker.com/docker-hub/builds/
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read

    steps:
      - uses: actions/checkout@v3

      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"

      - name: Log in to registry
        # This is where you will update the PAT to GITHUB_TOKEN
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin

      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          # Change all uppercase to lowercase
          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
          # Strip git ref prefix from version
          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
          # Strip "v" prefix from tag name
          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # Use Docker `latest` tag convention
          [ "$VERSION" == "master" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION