CI Falha com Zig — Resolver Problemas em Pipelines CI/CD
Configurar Zig em pipelines CI/CD pode apresentar desafios específicos. Este guia resolve os problemas mais comuns com GitHub Actions, GitLab CI e outros sistemas.
GitHub Actions: Configuração Básica
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Instalar Zig
uses: goto-bus-stop/setup-zig@v2
with:
version: 0.13.0 # Fixar versão!
- name: Build
run: zig build
- name: Testes
run: zig build test
- name: Build Release
run: zig build -Doptimize=ReleaseSafe
Erro: Versão do Zig Não Especificada
Problema: Usar “latest” pode quebrar quando sai uma nova versão.
# ERRADO: pode quebrar sem aviso
- uses: goto-bus-stop/setup-zig@v2
with:
version: latest
# CORRETO: versão fixa
- uses: goto-bus-stop/setup-zig@v2
with:
version: 0.13.0
Regra: Sempre fixe a versão do Zig no CI. Atualize manualmente e com testes.
Erro: Testes Passam Localmente mas Falham no CI
Causas comuns:
- Diferença de OS — CI roda Linux, você desenvolve em macOS/Windows
- Diferença de versão do Zig
- Dependência de arquivos locais que não estão no repositório
- Testes com timing que falham em máquinas lentas
# Testar em múltiplas plataformas
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: goto-bus-stop/setup-zig@v2
with:
version: 0.13.0
- run: zig build test
Erro: Timeout no CI
Causa: Compilação Release é demorada e pode exceder o timeout.
# Aumentar timeout
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 30 # Padrão é 6h, mas ser explícito é bom
steps:
- uses: actions/checkout@v4
- uses: goto-bus-stop/setup-zig@v2
with:
version: 0.13.0
- run: zig build -Doptimize=ReleaseFast
Cache para Acelerar o CI
# Cache do Zig
- name: Cache Zig
uses: actions/cache@v4
with:
path: |
~/.cache/zig
zig-cache
.zig-cache
key: zig-${{ runner.os }}-${{ hashFiles('build.zig', 'build.zig.zon') }}
restore-keys: |
zig-${{ runner.os }}-
Cross-Compilation no CI
# Compilar para múltiplos targets
jobs:
cross-compile:
runs-on: ubuntu-latest
strategy:
matrix:
target:
- x86_64-linux-gnu
- aarch64-linux-gnu
- x86_64-windows
- x86_64-macos
steps:
- uses: actions/checkout@v4
- uses: goto-bus-stop/setup-zig@v2
with:
version: 0.13.0
- name: Build para ${{ matrix.target }}
run: zig build -Dtarget=${{ matrix.target }} -Doptimize=ReleaseSafe
- name: Upload artefato
uses: actions/upload-artifact@v4
with:
name: build-${{ matrix.target }}
path: zig-out/bin/
GitLab CI
# .gitlab-ci.yml
image: ubuntu:22.04
variables:
ZIG_VERSION: "0.13.0"
before_script:
- apt-get update && apt-get install -y wget xz-utils
- wget https://ziglang.org/download/${ZIG_VERSION}/zig-linux-x86_64-${ZIG_VERSION}.tar.xz
- tar xf zig-linux-x86_64-${ZIG_VERSION}.tar.xz
- export PATH=$PATH:$(pwd)/zig-linux-x86_64-${ZIG_VERSION}
build:
stage: build
script:
- zig build
- zig build test
release:
stage: deploy
script:
- zig build -Doptimize=ReleaseSafe
artifacts:
paths:
- zig-out/bin/
Erro: Dependências Não Baixam no CI
# Se o CI não tem acesso à internet para dependências
# Opção 1: Cache das dependências
- name: Cache dependências Zig
uses: actions/cache@v4
with:
path: ~/.cache/zig
key: zig-deps-${{ hashFiles('build.zig.zon') }}
# Opção 2: Vendor das dependências (incluir no repo)
# zig fetch --save URL (localmente, commit o resultado)
# Opção 3: Pre-fetch
- name: Fetch dependências
run: zig build --fetch
Docker no CI
# Usando imagem Docker com Zig
jobs:
build:
runs-on: ubuntu-latest
container:
image: euantorano/zig:0.13.0
steps:
- uses: actions/checkout@v4
- run: zig build
- run: zig build test
Release Automática
# Criar release com binários
name: Release
on:
push:
tags: ['v*']
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: goto-bus-stop/setup-zig@v2
with:
version: 0.13.0
- name: Build Linux
run: zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe
- name: Build Windows
run: zig build -Dtarget=x86_64-windows -Doptimize=ReleaseSafe
- name: Criar Release
uses: softprops/action-gh-release@v1
with:
files: |
zig-out/bin/*
Diagnóstico de Problemas no CI
# Adicionar informações de debug
- name: Info do ambiente
run: |
zig version
zig env
uname -a
free -h
df -h
- name: Build verbose
run: zig build --verbose 2>&1 | tail -50
Checklist para CI com Zig
- Versão do Zig fixada (nunca usar “latest”)
- Cache configurado para
.zig-cachee~/.cache/zig - Testes rodam em todos os OS alvos
- Timeout adequado para builds Release
- Dependências acessíveis (cache ou vendored)
- Artefatos salvos para deploy
- Build verbose habilitado para diagnóstico
Veja Também
- FAQ Build System — Configuração de build
- FAQ Produção — Deploy em produção
- Atualizar Versão — Migrar versões no CI
- Cross-Compile Falha — Cross-compilation
- Teste Falha — Resolver testes falhando