Publicando imagens do Docker

Neste tutorial, você aprenderá a publicar imagens do Docker em um registro, como Docker Hub ou GitHub Packages, como parte do fluxo de trabalho de CI (integração contínua).

Neste artigo

Introdução

Este guia mostra como criar um fluxo de trabalho que executa um build do Docker e, em seguida, publica imagens do Docker para Docker Hub ou GitHub Packages. Com um único fluxo de trabalho, você pode publicar imagens em um único registro ou em vários registros.

Observação

Se você quiser fazer push para outro registro Docker de terceiros, o exemplo na seção Publicando imagens no GitHub Packages poderá servir como um bom modelo.

Pré-requisitos

Recomendamos que você tenha um entendimento básico das opções de configuração do fluxo de trabalho e de como criar um arquivo do fluxo de trabalho. Para saber mais, confira Escrevendo fluxos de trabalho.

Você também pode achar útil ter um entendimento básico do seguinte:

  •         [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions)

  •         [AUTOTITLE](/actions/security-guides/automatic-token-authentication)

  •         [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-docker-registry)

Sobre a configuração da imagem

Este guia pressupõe que você tenha uma definição completa para uma imagem do Docker armazenada em um GitHub repositório. Por exemplo, seu repositório precisa conter um Dockerfile e todos os outros arquivos necessários para executar um build do Docker para criar uma imagem.

          Você pode usar chaves de anotação pré-definidas para adicionar metadados, incluindo uma descrição, uma licença e um repositório de origem à imagem de contêiner. Para obter mais informações, consulte [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#labelling-container-images).

Neste guia, usaremos a ação build-push-action do Docker para compilar a imagem do Docker e efetuar push dela para um ou mais registros do Docker. Para obter mais informações, confira build-push-action.

Observação

O GitHub Actions no GitHub Enterprise Server pode ter acesso limitado às ações do GitHub.com ou do GitHub Marketplace. Para saber mais, confira Gerenciando o acesso a ações de GitHub.com e entre em contato com o administrador do site do GitHub Enterprise.

Publicando imagens no Docker Hub

Observação

O Docker Hub normalmente impõe limites de taxa em operações de push e pull, o que afetará os trabalhos em executores auto-hospedados. No entanto, executores hospedados pelo GitHub não estão sujeitos a esses limites com base em um contrato entre o GitHub e o Docker.

Você pode acionar um fluxo de trabalho para publicar sua imagem sempre que criar uma nova versão no GitHub. O fluxo de trabalho no exemplo abaixo é executado quando o evento release é disparado com o tipo de atividade published.

No exemplo de fluxo de trabalho abaixo, usamos as ações do Docker login-action e build-push-action para criar a imagem do Docker e, se o build for bem-sucedido, efetuar push da imagem compilada para Docker Hub.

Para enviar por push para Docker Hub, você precisará ter uma conta Docker Hub e ter um repositório Docker Hub criado. Para obter mais informações, consulte Envio de uma imagem de contêiner do Docker para o Docker Hub na documentação do Docker.

As opções de login-action necessárias para Docker Hub são: * username e password: este é seu nome de usuário e senha Docker Hub. Recomendamos armazenar seu nome de usuário e senha Docker Hub como segredos para que eles não sejam expostos no arquivo de fluxo de trabalho. Para saber mais, confira Usar segredos em ações do GitHub.

A opção metadata-action necessária para Docker Hub é: * images: o namespace e o nome da imagem do Docker que você está criando/enviando por push para Docker Hub.

As opções de build-push-action necessárias para Docker Hub são: * tags: a marca da nova imagem no formato DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION. Você pode definir uma única tag, conforme mostrado abaixo, ou especificar várias tags em uma lista. * push: se isso for definido como true, a imagem será enviada por push para o registro se for compilada com sucesso.

YAML
# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

# O GitHub recomenda fixar ações em um SHA de commit.
# Para obter uma versão mais recente, você precisará atualizar o SHA.
# Você também pode fazer referência a uma marca ou branch, mas a ação pode ser alterada sem aviso.

name: Publish Docker image

on:
  release:
    types: [published]

jobs:
  push_to_registry:
    name: Push Docker image to Docker Hub
    runs-on: [self-hosted]
    permissions:
      packages: write
      contents: read
      
      
    steps:
      - name: Check out the repo
        uses: actions/checkout@v5

      - name: Log in to Docker Hub
        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: my-docker-hub-namespace/my-docker-hub-repository

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

O fluxo de trabalho acima clona o GitHub repositório, usa o login-action para fazer login no registro e, em seguida, usa a ação build-push-action para: criar uma imagem do Docker com base no Dockerfile; efetuar push da imagem para Docker Hub e aplicar uma tag à imagem.

Publicando imagens para GitHub Packages

Observação

Atualmente, o Container registry está em versão prévia pública no GitHub Enterprise Server e sujeito a alterações.

O GitHub Packages e o isolamento de subdomínio devem ser habilitados para usar o Container registry. Para saber mais, confira Trabalhando com o registro de contêiner.

Sempre que você criar uma nova versão no GitHub, poderá iniciar um workflow para publicar sua imagem. O fluxo de trabalho no exemplo abaixo é executado quando uma alteração é enviada por push para o branch release.

No fluxo de trabalho de exemplo abaixo, usamos as ações Docker login-action, e build-push-action para criar a imagem do Docker e, se o build for bem-sucedido, enviar a imagem construída para GitHub Packages.

As opções login-action necessárias para GitHub Packages são: * registry: deve ser definido como containers.HOSTNAME. * username: você pode usar o ${{ github.actor }} contexto para usar automaticamente o nome de usuário do usuário que disparou a execução do fluxo de trabalho. Para saber mais, confira Referência de contextos. * password: use o segredo GITHUB_TOKEN gerado automaticamente para a senha. Para saber mais, confira Usar GITHUB_TOKEN para autenticação em fluxos de trabalho.

As opções necessárias para GitHub Packages são build-push-action: * push: se definido como true, a imagem será enviada por push para o Registro se for criada com êxito. * tags: precisa ser definido no formato containers.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION.

Por exemplo, para uma imagem nomeada octo-image armazenada em GitHub Enterprise Serverhttps://HOSTNAME/octo-org/octo-repo, a opção tags deve ser definida como containers.HOSTNAME/octo-org/octo-repo/octo-image:latest . Você pode definir uma única marca, conforme mostrado abaixo, ou especificar várias marcas em uma lista.

Observação

  • Esse fluxo de trabalho usa ações que não são certificadas por GitHub. Elas são fornecidas por terceiros e regidar por termos de serviço, política de privacidade e documentação de suporte separados.
  • GitHub recomenda fixar ações em um SHA de confirmação. Para obter uma versão mais recente, você precisará atualizar o SHA. Você também pode fazer referência a uma marca ou branch, mas a ação pode ser alterada sem aviso.
YAML
name: Create and publish a Docker image
on:
  push:
    branches: ['release']

Configures this workflow to run every time a change is pushed to the branch called release.

env:
  REGISTRY: containers.HOSTNAME
  IMAGE_NAME: ${{ github.repository }}

Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.

jobs:
  build-and-push-image:
    runs-on: [self-hosted]

There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.

    permissions:
      contents: read
      packages: write

Sets the permissions granted to the GITHUB_TOKEN for the actions in this job.

    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

Uses the docker/login-action action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.

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

This step uses docker/metadata-action to extract tags and labels that will be applied to the specified image. The id "meta" allows the output of this step to be referenced in a subsequent step. The images value provides the base name for the tags and labels.

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

This step uses the docker/build-push-action action to build the image, based on your repository's Dockerfile. If the build succeeds, it pushes the image to GitHub Packages. It uses the context parameter to define the build's context as the set of files located in the specified path. For more information, see Usage in the README of the docker/build-push-action repository. It uses the tags and labels parameters to tag and label the image with the output from the "meta" step.

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['release']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: containers.HOSTNAME
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: [self-hosted]
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      
      
      #
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

O fluxo de trabalho acima é acionado por um push para o branch da "versão". Ele verifica o repositório GitHub e usa o login-action para fazer logon no Container registry. Em seguida, extrai etiquetas e tags para a imagem do Docker. Por fim, ele usa a ação build-push-action para criar a imagem e publicá-la no Container registry.

Publicando imagens em Docker Hub e GitHub Packages

Observação

Atualmente, o Container registry está em versão prévia pública no GitHub Enterprise Server e sujeito a alterações.

O GitHub Packages e o isolamento de subdomínio devem ser habilitados para usar o Container registry. Para saber mais, confira Trabalhando com o registro de contêiner.

Em um fluxo de trabalho individual, você pode publicar sua imagem do Docker em vários registros usando as ações login-action e build-push-action para cada registro.

O fluxo de trabalho de exemplo a seguir usa as etapas das seções anteriores (Publicando imagens no Docker Hub e Publicando imagens em GitHub Packages) para criar um único fluxo de trabalho que faz push para ambos os registros.

YAML
# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

# O GitHub recomenda fixar ações em um SHA de commit.
# Para obter uma versão mais recente, você precisará atualizar o SHA.
# Você também pode fazer referência a uma marca ou branch, mas a ação pode ser alterada sem aviso.

name: Publish Docker image

on:
  release:
    types: [published]

jobs:
  push_to_registries:
    name: Push Docker image to multiple registries
    runs-on: [self-hosted]
    permissions:
      packages: write
      contents: read
    steps:
      - name: Check out the repo
        uses: actions/checkout@v5

      - name: Log in to Docker Hub
        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: containers.HOSTNAME
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: |
            my-docker-hub-namespace/my-docker-hub-repository
            containers.HOSTNAME/${{ github.repository }}

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

O fluxo de trabalho acima verifica o GitHub repositório, usa as login-action duas vezes para fazer logon em ambos os registros e gera marcas e rótulos com a ação metadata-action . Em seguida, a ação build-push-action cria e faz push da imagem do Docker para o Docker Hub e o Container registry.

Atividade prática

Pratique a publicação de imagens Docker com o exercício Publicação de Imagens DockerGitHub Skills.

Neste exercício, você aprenderá a:

  • Autentique-se em GitHub Packages usando o GITHUB_TOKEN.
  • Criar e publicar imagens de contêiner no Container registry (ghcr.io).
  • Use ações oficiais do Docker, como docker/login-action, docker/build-push-actione docker/setup-buildx-action.
  • Gere marcas automaticamente com docker/metadata-action base em branches, solicitações de pull e versões.
  • Crie funcionalidades, pull requests e versões com o versionamento de contêiner apropriado.