---
title: "Zig Supply Chain: Dependências, Hashes e Releases Confiáveis"
url: "https://ziglang.com.br/artigos/zig-supply-chain-dependencias-releases/"
markdown_url: "https://ziglang.com.br/artigos/zig-supply-chain-dependencias-releases.MD"
description: "Como proteger a supply chain de projetos Zig: toolchain fixada, build.zig.zon, hashes, revisão de dependências, checksums, SBOM e releases verificáveis."
date: "2026-05-24"
author: ""
---

# Zig Supply Chain: Dependências, Hashes e Releases Confiáveis

Como proteger a supply chain de projetos Zig: toolchain fixada, build.zig.zon, hashes, revisão de dependências, checksums, SBOM e releases verificáveis.


Supply chain deixou de ser preocupação exclusiva de equipes enormes. Um projeto Zig pequeno também baixa compilador, importa bibliotecas C, usa pacotes declarados no `build.zig.zon`, roda em CI, publica binários e talvez empacote tudo em container. Se uma dessas etapas é frouxa, o binário final pode ser difícil de reproduzir, auditar ou confiar.

Zig ajuda porque favorece builds explícitos. O compilador tem cross-compilation forte, o sistema de build é código Zig, dependências podem ser fixadas por URL e hash, e releases costumam virar binários pequenos. Mas nenhuma linguagem elimina a disciplina operacional. Você ainda precisa saber qual versão do Zig compilou o artefato, de onde vieram as dependências, quais hashes foram aceitos, quem revisou a atualização e como o usuário final confere o download.

Este guia mostra uma abordagem prática para **supply chain em projetos Zig**: fixar toolchain, tratar `build.zig.zon` como contrato de integridade, revisar dependências como código, gerar checksums de release, pensar em SBOM sem burocracia e manter containers e CI reproduzíveis. Ele complementa o guia de [package manager e build.zig.zon](/artigos/zig-package-manager-guia-build-zig-zon/), o material de [GitHub Actions para release multiplataforma](/artigos/zig-github-actions-release-multiplataforma/), o artigo de [Docker para Zig em produção](/artigos/zig-docker-containers/) e o checklist de [configuração segura](/artigos/zig-configuracao-segura-segredos-env/).

## O que é supply chain em um projeto Zig

Supply chain é a cadeia que transforma código-fonte em software executável. Em Zig, ela normalmente inclui:

- versão do compilador Zig;
- scripts em `build.zig`;
- dependências em `build.zig.zon`;
- bibliotecas C importadas com `@cImport` ou linkadas no build;
- comandos de CI;
- imagens Docker usadas para build ou runtime;
- artefatos publicados, como `.tar.gz`, `.zip`, `.exe` e checksums;
- segredos de release, como tokens de GitHub, Gitea, registry ou signing.

O erro comum é olhar apenas para código de aplicação e esquecer que o build também executa código. Um `build.zig` pode baixar, compilar, linkar, copiar arquivos e mudar flags. Uma action de CI pode usar versão flutuante. Um Dockerfile pode puxar imagem `latest`. Uma dependência C pode mudar sem passar pela mesma revisão que um arquivo `.zig`.

O objetivo não é criar paranoia. É criar rastreabilidade suficiente para responder três perguntas: o que entrou no binário, quem aprovou a mudança e como reconstruir o mesmo resultado.

## Fixe a versão do Zig

Projetos Zig mudam junto com a linguagem. Isso é normal em uma tecnologia pré-1.0, mas significa que a versão do compilador é parte da supply chain. Não basta dizer "use Zig". Diga qual Zig.

Documente a versão em `README.md`, fixe no CI e, quando possível, use uma ferramenta de versionamento como `zigup` ou uma imagem de build com tag explícita. Se o projeto publica binários, inclua a versão do Zig nas notas de release.

```yaml
env:
  ZIG_VERSION: 0.14.1

steps:
  - uses: actions/checkout@v4
  - uses: mlugg/setup-zig@v2
    with:
      version: ${{ env.ZIG_VERSION }}
  - run: zig build test
```

Evite `master`, `nightly` ou `latest` como default de produção. Nightly pode ser útil para experimentar recursos novos, mas o release deve nascer de uma toolchain previsível. Quando atualizar Zig, trate como mudança real: rode testes, atualize lock de dependências se necessário, revise warnings e publique no changelog.

## Trate build.zig.zon como contrato

O `build.zig.zon` não é só lista de pacotes. Ele é parte do contrato de integridade do projeto. O campo `.hash` permite verificar se o conteúdo baixado é exatamente o esperado. Isso evita uma classe inteira de problemas comuns em ecossistemas que resolvem dependências de forma mais implícita.

Um trecho típico fica assim:

```zig
.dependencies = .{
    .zap = .{
        .url = "https://github.com/zigzap/zap/archive/refs/tags/v0.9.1.tar.gz",
        .hash = "1220...",
    },
},
```

Não edite esse hash no olho. Use `zig fetch --save` para registrar a origem e o hash calculado pelo próprio tooling. Se o hash mudou sem você mudar a versão ou a URL, trate como sinal de alerta: o arquivo remoto pode ter sido reempacotado, a tag pode ter sido movida ou você pode estar apontando para uma origem instável.

Para dependências críticas, prefira releases versionadas ou commits imutáveis em vez de branches. Branch é bom para desenvolvimento, ruim para auditoria. Tag também pode ser movida em alguns hosts, então projetos mais exigentes usam URL de archive por commit ou espelham artefatos internos.

## Revise dependências como código

Atualização de dependência não deve ser commit mecânico sem leitura. Em Zig, o ecossistema ainda é menor que Rust, Go ou npm, então cada dependência nova pesa mais. Pergunte:

- a dependência é necessária ou o problema cabe na biblioteca padrão?
- ela executa código no build?
- ela puxa código C ou ferramentas externas?
- a licença é compatível com o produto?
- há releases, tags e changelog?
- o projeto tem manutenção recente?
- o código manipula entrada externa, rede, criptografia, arquivos ou parser?

Se a dependência é pequena, leia o código. Se é grande, leia pelo menos o diff da versão que você está adotando, exemplos de uso e issues abertas sobre segurança ou quebra de API. Para bibliotecas C, verifique também flags de compilação, CVEs conhecidas e se a versão linkada é a mesma que você acha que está usando.

Zig torna muito fácil chamar C, como explicado em [interoperabilidade com C](/artigos/zig-interoperabilidade-c/). Essa facilidade é uma vantagem, mas também amplia a superfície de supply chain. Um header importado pode esconder macros complexas, uma biblioteca estática pode vir de origem não auditada e uma dependência do sistema pode variar entre distros.

## Separe dependência de build e dependência de runtime

Nem tudo que participa do build precisa existir em produção. Essa separação reduz risco e tamanho de artefato.

Um serviço HTTP Zig pode precisar de `zig`, `git`, compilador C, headers e ferramentas de teste no CI. O container de runtime, por outro lado, talvez precise só do binário, certificados CA, usuário sem root e variáveis de ambiente. Essa é a lógica do guia de [containers pequenos e seguros](/artigos/zig-docker-containers/): imagem mínima, mas operável.

Em Docker, evite imagens flutuantes:

```dockerfile
FROM alpine:3.20 AS runtime
RUN adduser -D -u 10001 app
COPY zig-out/bin/servico /usr/local/bin/servico
USER 10001
ENTRYPOINT ["/usr/local/bin/servico"]
```

Se a build usa uma imagem com Zig instalado, fixe tag ou digest. Tag explícita já é melhor que `latest`; digest é melhor quando o ambiente exige reprodutibilidade forte. O mesmo vale para actions de CI: usar `actions/checkout@v4` é mais previsível que apontar para branch sem versão.

## Gere checksums de release

Usuário que baixa um binário precisa de uma forma simples de conferir integridade. O mínimo é publicar SHA-256 para cada artefato. Em releases multiplataforma, gere checksums no mesmo job que monta os arquivos finais.

```sh
sha256sum dist/* > dist/checksums.txt
```

O arquivo deve listar exatamente os nomes publicados:

```text
2d7f...  minha-cli-linux-x86_64.tar.gz
9ab1...  minha-cli-macos-aarch64.tar.gz
f01c...  minha-cli-windows-x86_64.zip
```

Para projetos internos, isso já ajuda a investigar deploy errado, cache corrompido e upload parcial. Para projetos públicos, considere também assinatura com ferramenta adequada ao seu fluxo, como Sigstore, minisign, GPG ou signing do registry. Não comece pela ferramenta mais sofisticada se o projeto nem publica checksums; comece pelo básico confiável.

## SBOM sem teatro

SBOM, ou Software Bill of Materials, é uma lista dos componentes que entram em um software. Em grandes empresas, SBOM pode virar exigência de compliance. Em projeto pequeno, ele ainda é útil como inventário: versão do Zig, dependências Zig, bibliotecas C linkadas, imagem base e artefatos finais.

O cuidado é não produzir um arquivo bonito que ninguém usa. Um SBOM simples e honesto vale mais que um relatório automático incompleto. Para Zig, inclua pelo menos:

- versão do compilador;
- target e modo de otimização (`ReleaseSafe`, `ReleaseFast`, `ReleaseSmall`);
- dependências do `build.zig.zon` com URL e hash;
- bibliotecas C linkadas;
- imagem base de runtime, se houver;
- commit do repositório;
- checksums dos artefatos.

Quando o ambiente pede formato padrão, use CycloneDX ou SPDX. Quando não pede, um `RELEASE.md` gerado pelo CI já melhora muito a rastreabilidade.

## Proteja segredos do pipeline

Supply chain também falha por vazamento de token. Token de registry, chave de assinatura, credencial de deploy e webhook de release não pertencem ao repositório, ao Dockerfile, ao `build.zig.zon` nem ao log do CI.

Use o secret manager da plataforma e limite permissões. Um job que roda testes não precisa ter token de publicação. Um job que publica release não precisa rodar em pull request de fork com segredo disponível. Um token de deploy deve publicar artefato, não administrar todo o repositório.

No código Zig, siga a mesma fronteira do artigo de [configuração segura](/artigos/zig-configuracao-segura-segredos-env/): segredo entra pelo ambiente ou secret manager, é validado no boot e não aparece em log. No CI, a regra é parecida: segredo entra no passo mínimo necessário, não é impresso e não é passado como argumento de build quando isso pode ficar em histórico.

## Checklist prático para projetos Zig

Antes de publicar um release, revise:

- versão do Zig fixada no CI e documentada;
- `zig fmt --check` e `zig build test` rodando;
- dependências em `build.zig.zon` com URL e hash;
- nenhuma dependência nova sem revisão humana;
- actions e imagens Docker sem `latest` desnecessário;
- segredos isolados por job;
- binários gerados por target esperado;
- checksums SHA-256 publicados;
- artefatos têm nomes claros com sistema e arquitetura;
- notas de release citam commit, versão do Zig e mudanças relevantes;
- container final roda sem root quando aplicável;
- logs de CI não mostram token, chave ou DSN.

Esse checklist conversa diretamente com [code review em Zig](/artigos/zig-code-review-checklist/). Revisão boa não olha só para função nova; olha para o caminho que transforma a função em binário distribuído.

## Comparação com Go e Rust

Go tem módulos maduros, checksum database e tooling de release muito estabelecido. Rust tem Cargo, `Cargo.lock`, crates.io, `cargo audit` e uma cultura forte de lockfile. Zig ainda está em uma fase mais explícita e menos automatizada: você ganha controle, mas precisa montar algumas peças com mais intenção.

Isso não é necessariamente ruim. Para sistemas pequenos, CLIs, agentes e binários de infraestrutura, a simplicidade de Zig pode ser vantagem. Há menos camadas mágicas entre fonte e artefato. O preço é que o time precisa documentar o caminho.

Se você está comparando culturas de supply chain, vale estudar também os materiais de <a href="https://golang.com.br/" target="_blank" rel="noopener noreferrer" onclick="umami.track('portfolio-site-click', { destination: 'golang.com.br' })">Go no Brasil</a> para tooling operacional e <a href="https://rustlang.com.br/" target="_blank" rel="noopener noreferrer" onclick="umami.track('portfolio-site-click', { destination: 'rustlang.com.br' })">Rust no Brasil</a> para auditoria de crates e segurança de dependências. A decisão prática não é qual linguagem tem marketing melhor; é qual cadeia você consegue operar, revisar e reproduzir.

## Comece pequeno e verificável

Um bom plano incremental para supply chain Zig é:

1. fixar versão do Zig;
2. remover `latest` de CI e Docker;
3. garantir `build.zig.zon` com hashes corretos;
4. adicionar job de teste e build por target;
5. gerar checksums de release;
6. documentar dependências C e imagem base;
7. separar permissões de teste, build e publicação;
8. criar um pequeno inventário de release.

Depois disso, você pode avaliar assinatura, SBOM formal, provenance, SLSA e políticas mais rígidas. Mas o salto inicial já resolve a maior parte dos riscos comuns: artefato sem origem clara, dependência flutuante, release difícil de reproduzir e segredo exposto no pipeline.

Zig combina bem com software verificável porque deixa muita coisa explícita. Aproveite essa característica. Um binário pequeno é bom; um binário pequeno, rastreável e reconstruível é melhor.

## Próximos passos

- [Package manager e build.zig.zon](/artigos/zig-package-manager-guia-build-zig-zon/) — aprofunde dependências e hashes.
- [GitHub Actions para releases Zig](/artigos/zig-github-actions-release-multiplataforma/) — monte a matriz de build e artefatos.
- [Zig e Docker em 2026](/artigos/zig-docker-containers/) — reduza a imagem final sem perder operação.
- [Configuração segura em Zig](/artigos/zig-configuracao-segura-segredos-env/) — trate segredos como fronteira de produção.
- [Code review em Zig](/artigos/zig-code-review-checklist/) — leve supply chain para a revisão diária.