Publicar e usar pacotes Rust no Forgejo

O Forgejo tem um registry Cargo embutido, então dá para hospedar seus próprios pacotes Rust (crates) sem depender do crates.io. Este guia usa como exemplo o pacote term-colors, publicado em cosmos.simioni.dev.br, na organização projetos-rust.

Visão geral

O quê	Onde vive	Como sobe
Código-fonte	Repositório Git	git push
Pacote (crate)	Registry Cargo da organização	cargo publish --registry forgejo

São duas coisas separadas: o Git guarda o histórico e o registry guarda as versões publicadas, que são imutáveis.

Configuração única (por máquina)

1. Instalar o Rust

mise use -g Este endereço de email está sendo protegido de spambots. Você precisa do JavaScript ativado para vê-lo..1

2. Criar um token no Forgejo

Vá em Configurações → Aplicativos e crie um token com permissão de leitura e escrita em package. O usuário dono do token precisa ser membro da organização.

3. Configurar o registry

Edite o arquivo ~/.cargo/config.toml (no Windows, C:\Users\SEU-USUARIO\.cargo\config.toml):

[registries.forgejo]
index = "sparse+https://cosmos.simioni.dev.br/api/packages/projetos-rust/cargo/"
credential-provider = "cargo:wincred"

• projetos-rust é o dono dos pacotes (organização ou usuário).
• O credential-provider é obrigatório quando o registry exige autenticação. O cargo:wincred guarda o token no Gerenciador de Credenciais do Windows. Uma alternativa mais simples, porém menos segura, é cargo:token.

4. Fazer login

cargo login --registry forgejo

Cole o token com o prefixo Bearer e um espaço, no formato Bearer SEU_TOKEN. Sem o prefixo, o Forgejo responde com erro 401.

Publicar um pacote

Preparar o Cargo.toml

[package]
name = "term-colors"
version = "0.1.0"
edition = "2021"
rust-version = "1.75"
description = "A tiny enum of ANSI terminal colors"
license = "MIT"
readme = "README.md"
repository = "https://cosmos.simioni.dev.br/projetos-rust/term-colors"
keywords = ["terminal", "color", "ansi"]
categories = ["command-line-interface"]
publish = ["forgejo"]

A linha publish = ["forgejo"] impede que o pacote seja publicado por engano no crates.io.

Checklist antes de cada release

cargo fmt --check
cargo clippy -- -D warnings
cargo test
git status
cargo package --list
cargo publish --dry-run --registry forgejo

A árvore do Git precisa estar limpa, com tudo commitado. Caso contrário o Cargo se recusa a empacotar.

Publicar e marcar a versão

cargo publish --registry forgejo
git tag v0.1.0
git push origin main v0.1.0

Publicar uma nova versão

1. Aumente o version no Cargo.toml, seguindo o versionamento semântico (SemVer).
2. Atualize o CHANGELOG.md.
3. Faça o commit, rode o checklist, publique e crie a tag.

Uma versão publicada não pode ser sobrescrita. Para corrigir algo, publique uma nova versão.

Usar um pacote em outro projeto

Com o registry configurado e o login feito, adicione a dependência:

cargo add term-colors --registry forgejo

Ou escreva manualmente no Cargo.toml:

[dependencies]
term-colors = { version = "0.1", registry = "forgejo" }

Depois é só usar no código:

use term_colors::Color;

fn main() {
    println!("{}", Color::Red.paint("erro"));
}

Para atualizar para versões novas compatíveis, rode cargo update. Quem clonar o projeto também precisa ter o registry e o login configurados, senão o cargo build não resolve a dependência.

Problemas comuns

Sintoma	Causa e solução
authenticated registries require a credential-provider	Falta o credential-provider no config.toml.
Erro 401 com token does not include an authentication scheme	O token foi guardado sem o Bearer. Refaça o cargo login.
Erro 401 ou 403 mesmo com Bearer	O token não tem leitura e escrita em package, ou o usuário não é membro da organização.
Erro 404	O nome do dono na URL do índice está errado.
Alterações não commitadas	Faça o commit antes de publicar.
Versão já existe	Aumente o version e publique de novo.

Segurança

• Nunca cole o token em chats, issues ou commits. Se ele vazar, revogue no Forgejo e gere outro.
• Use publish = ["forgejo"] para evitar publicações acidentais no crates.io.
• Nunca versione o arquivo credentials.toml.

Padrão de estrutura de um pacote

nome-do-pacote/
├── Cargo.toml
├── README.md
├── CHANGELOG.md
├── LICENSE-MIT
├── src/lib.rs
├── examples/
├── tests/
└── .gitignore

Convenções adotadas: identificadores e documentação em inglês, crates em kebab-case, tipos em PascalCase, funções em snake_case, #![forbid(unsafe_code)], #![warn(missing_docs)] e #[non_exhaustive] em enums públicos.