CI/CD: Deploy de containers para o GHCR com GitHub Actions

Summary

Introduction

Enquanto estudamos DevOps e aplicações em containers, uma das primeiras coisas que aprendemos é: Como criar um pipeline de deploy para que seus containers/imagens sejam construídos, etiquetados e enviados automaticamente.

Neste post, vou mostrar como configurei um workflow de CI/CD usando o GitHub Actions para publicar containers/imagens no GitHub Container Registry (GHCR).

O que é CI/CD?

O CI/CD significa Integração Contínua e Entrega (ou Deploy) Contínua.

• CI: Automatiza o processo de testar e construir o código sempre que você envia alterações.
• CD: Automatiza o deploy, colocando seu código em um ambiente (ex: produção/desenvolvimento).

Usando ambos, você garante que cada mudança seja integrada, testada, construída e entregue rapidamente.

O que é o GHCR (GitHub Container Registry)?

O GHCR é o registro de containers nativo do GitHub, semelhante ao Docker Hub , porém mais integrado ao GitHub. Ele permite que você:

1. Armazene e gerencie containers/imagens
2. Associe imagens diretamente aos repositórios
3. Controle o acesso via permissões do GitHub

É gratuito para repositórios públicos e também suporta hospedagem privada de imagens. Além disso, funciona perfeitamente com o GitHub Actions.

Fluxo do CI/CD

Aqui está um fluxo visual para o CI/CD:

Visão geral do aplicativo

Para este post, criei um simples webapp em Golang. Você pode encontrar o código no repositório do GitHub:

labs/blog/actions-containers-ghcr at main · LucJosin/labs

This repository contains projects from my blog posts, experiments, and learning activities - LucJosin/labs

github.com

Configurando o Dockerfile

Antes de configurar nosso workflow do GitHub Actions, vamos definir o Dockerfile, que descreve como construir e executar nosso aplicativo Go dentro de um contêiner.

Aqui está o Dockerfile completo:

1
# ---- Etapa de Build ----
2
FROM golang:1.22-alpine AS builder
3

4
# Definir diretório de trabalho
5
WORKDIR /app
6

7
# Instalar pacotes necessários
8
RUN apk add --no-cache git
9

10
# Copiar o arquivo go.mod
11
COPY go.mod ./
12

13
# Baixar dependências
14
RUN go mod download
15

16
# Copiar o restante do código-fonte
17
COPY . .
18

19
# Compilar a aplicação Go
20
RUN GOOS=linux go build -o app main.go
21

22
# ---- Etapa de Execução ----
23
FROM alpine:latest
24

25
# Definir diretório de trabalho
26
WORKDIR /app
27

28
# Copiar o binário e os arquivos de template da etapa de build
29
COPY --from=builder /app/app /app/index.tmpl ./
30

31
# Expor porta
32
EXPOSE 8080
33

34
# Executar a aplicação
35
CMD ["./app"]

Neste caso, usamos um Dockerfile de múltiplas etapas:

1. Build:

   • Configura o ambiente Go utilizando uma imagem (com Golang configurado).
   • Instala pacotes necessários (como o Git, usado para buscar dependências do Go).
   • Copia o código-fonte e os arquivos de módulos.
   • Baixa as dependências com go mod download.
   • Compila a aplicação em um binário usando go build.

2. Run:

   • Utiliza uma imagem (base) leve para manter a imagem final pequena.
   • Copia o binário compilado da fase de build.
   • Define o diretório de trabalho.
   • Expondo a porta que o app usará.
   • Define o comando para rodar o app.

Configurando o GitHub Actions

Agora que definimos as instruções para construir a imagem, vamos configurar nosso workflow com o arquivo build.yml, este arquivo diz ao GitHub Actions como e quando executar ações/passos/tarefas automatizadas.

O GitHub permite que você tenha múltiplos workflows, todas as configurações .yaml devem estar no diretório .github/workflows/.

Aqui está o arquivo completo de workflow:

1
# Nome do workflow exibido no GitHub Actions
2
name: 'Build e Push para GHCR'
3

4
# Aciona o workflow quando um tag é enviado, como: v1.0.0
5
on:
6
  push:
7
    tags:
8
      - 'v[0-9].[0-9]+.[0-9]'
9

10
# Define variáveis de ambiente disponíveis para todos os passos
11
env:
12
  GHCR_TOKEN: ${{ secrets.GHCR_TOKEN }} # Token do GitHub Container Registry (definido nos segredos do repositório)
13
  CONTAINER_NAME: lucjosin/go-webapp-ghcr # Nome da imagem a ser publicada (tudo minúsculo)
14
  USER_NAME: LucJosin # Nome de usuário do GitHub usado para autenticação no GHCR
15

16
jobs:
17
  build-and-push:
18
    runs-on: ubuntu-latest # Usa o runner mais recente do Ubuntu
19

20
    steps:
21
      # Passo 1
22
      - name: Configurar checkout
23
        uses: actions/checkout@v4
24

25
      # Passo 2
26
      - name: Configurar a tag git mais recente
27
        run: |
28
          RAW_TAG="${GITHUB_REF#refs/tags/}"
29
          VERSION="${RAW_TAG#*@}"
30
          echo "VERSION=${VERSION}" >> $GITHUB_ENV
31
          echo "Versão: $VERSION"
32

33
      # --- Etapa de Build ---
34

35
      # Passo 3
36
      - name: Build com Docker
37
        run: |
38
          docker build -t ghcr.io/${{ env.CONTAINER_NAME }}:latest .
39
          docker build -t ghcr.io/${{ env.CONTAINER_NAME }}:${{ env.VERSION }} .
40

41
      # --- Etapa de Push ---
42

43
      # Passo 4
44
      - name: Login no GitHub (GHCR)
45
        run: echo $GHCR_TOKEN | docker login ghcr.io -u $USER_NAME --password-stdin
46

47
      # Passo 5
48
      - name: Push no GitHub (GHCR)
49
        run: |
50
          docker push ghcr.io/${{ env.CONTAINER_NAME }}:latest
51
          docker push ghcr.io/${{ env.CONTAINER_NAME }}:${{ env.VERSION }}

O workflow contém os seguintes passos:

1. Configurar checkout: Configura o repositório de código (para que o workflow possa acessá-lo).
2. Configurar a tag git mais recente: Extrai a versão da última tag.
3. Build com Docker: Constrói a imagem, com tags nas versões: latest e env.VERSION (definida anteriormente).
4. Login no GitHub (GHCR): Faz login no GHCR.
5. Push no GitHub (GHCR): Envia as imagens para o GHCR.

Após publicar uma nova versão (como v1.0.0):

• Sua imagem aparecerá na seção Packages do seu repositório.
• Você pode puxá-la em qualquer host usando o caminho completo da imagem.

Preparando o Ambiente

Precisamos preparar o ambiente do repositório antes da execução do workflow, o que envolve: Atualizar permissões do workflow e Criar um token GHCR:

Atualizando permissões do workflow

Este workflow requer permissões adicionais para ser executado com sucesso. Isso garante que seus workflows tenham o acesso necessário para ler, escrever e acessar segredos, siga os passos no GIF abaixo para atualizá-las:

Você pode encontrar essas configurações na seção Settings > Actions > General do seu repositório.

Criando um token GHCR

Você pode acessar github.com/settings/tokens/new?scopes=write:packagespara criar um novo token, o parâmetro ?scopes=write:packages selecionará corretamente o escopo write:packages que será utilizado para baixar e enviar imagens de contêiner.

Se você não souber como adicionar um segredo em um Repositório GitHub, abra a caixa abaixo:

Acionando o workflow

Depois que o workflow do GitHub Actions for definido, você pode acioná-lo ao enviar uma nova tag que siga o padrão de versão definido no workflow:

1
git tag v1.0.0
2
git push origin v1.0.0

Após a tag ser enviada, o GitHub Actions irá automaticamente executar o CI/CD, construindo e publicando o app.

Se tudo correr bem, você verá o listado tanto na seção Releases quanto na seção Packages.

Usando a imagem

Agora que enviamos a imagem para o GHCR, podemos usar os seguintes métodos para puxar e rodar a aplicação localmente:

CLI

O primeiro método para puxar e rodar a imagem é usando o terminal com o Docker CLI:

1
docker run -d --name golang-app -p 8080:8080 ghcr.io/lucjosin/go-webapp-ghcr

Passo a passo:

1. docker run -d: Puxa e inicia um novo contêiner no modo detached.
2. —name golang-app: Define o nome golang-app para o contêiner.
3. -p 8080:8080: Abre a porta 8080 do contêiner para a porta 8080 do seu computador.
4. ghcr.io/lucjosin/go-webapp-ghcr: Esta é a imagem que está sendo puxada e executada (Lembre-se de usar a sua imagem).

Compose

O segundo método para puxar e rodar a imagem é usando o arquivo compose.yaml:

1
services:
2
  app:
3
    image: ghcr.io/lucjosin/go-webapp-ghcr
4
    container_name: golang-app
5
    ports:
6
      - '8080:8080'

Execute o seguinte comando no mesmo diretório que o arquivo:

1
docker compose up -d

Conclusão

Configurar o GitHub Actions e fazer o deploy para o GHCR é uma ótima introdução ao CI/CD no mundo DevOps. Isso reduz o trabalho manual e possibilita a criação de workflows automatizados mais completos.

Espero que esse post lhe dê um ponto de partida para automatizar seus próprios “deployments”.

Recursos e Referências

• docs.github.com/working-with-the-container-registry
• docs.github.com/about-workflows
• docs.docker.com/multi-stage