Também em: English, Español, 日本語 · Todos os guias em português

Aviso: desenvolvemos o Carbon Forge na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública, principalmente as seções "Cut a release" e "Publish to git" de Code and files on the substrate, a página de catálogo Archives e Source control settings, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Cada chamada é o exemplo da própria documentação, e as citações ficam em inglês com a tradução ao lado. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.

O modelo em duas frases

"A cut names the whole workspace's state at one moment and never moves." (Um corte nomeia o estado inteiro do workspace num momento e nunca se move.) "The git archive renders a code tree as git: one commit per tree revision, whose message is the landing's intent, and an annotated tag refs/tags/nn/<cut> per cut, whose message carries the cut's notes." (O arquivo git renderiza uma árvore de código como git: um commit por revisão da árvore, cuja mensagem é a intenção da integração, e uma tag anotada refs/tags/nn/<cut> por corte, cuja mensagem traz as notas do corte.) Como é renderizado "from the record byte for byte, so the same revision always renders to the same commit" (a partir do registro byte a byte, então a mesma revisão sempre gera o mesmo commit), a cópia no GitHub pode ser conferida com o registro a qualquer momento.

Passo 1. Integre o trabalho que a versão deve conter

Um corte nomeia o trunk, então o que ainda estiver numa lane fica de fora. Integre primeiro o que pertence à versão, com intenções que comecem por feat, fix, docs, chore ou revert: essa primeira palavra é como as notas agrupam cada integração (Integre uma mudança de código e a sua documentação num único changeset percorre uma integração).

Passo 2. Corte a versão

snapshots.cut { "name": "v1.4.0" }

O corte é permanente. A página do paradigma diz "the database refuses to change or remove a snapshot or a cut while the workspace exists" (o banco de dados se recusa a mudar ou remover um snapshot ou um corte enquanto o workspace existir). snapshots.materialize lê qualquer entidade como o corte a guarda, e trees.diff e trees.grep também aceitam um snapshot.

Passo 3. Leia as notas da versão

cuts.notes { "from": "v1.3.0", "to": "v1.4.0" }

cuts.notes "lists every changeset landed between the two cuts, grouped by the first word of its intent" (lista cada changeset integrado entre os dois cortes, agrupado pela primeira palavra da intenção), com a lane de onde cada um veio e os caminhos que tocou; path_glob restringe a uma parte do workspace. No app, /<workspace>/cuts/<name> abre nas mesmas notas, com o título Notes from <previous cut>, e Compare with another cut escolhe quaisquer dois.

Passo 4. Conecte uma conta do GitHub à instância

O push é feito "as the instance's GitHub App" (como a GitHub App da instância), então a App precisa estar instalada na conta dona do repositório. Um admin da instância abre Settings → Instance → Source control e clica em Connect a GitHub account, que leva o navegador à "GitHub's install page for the CarbonForge.dev GitHub App" (página de instalação do GitHub para a GitHub App do CarbonForge.dev). Ali você escolhe a conta ou organização e os repositórios. As permissões que a documentação lista:

Contents: Read and write, para enviar commits, refs/heads/main e a tag do corte.
Workflows: Read and write, necessária só quando o push adiciona ou altera um arquivo em .github/workflows/; sem ela "GitHub refuses" (o GitHub recusa).
Actions: Read, para ler as execuções do remoto no passo 8.

De volta ao Carbon Forge, a aba mostra Connected to @<account>.

Passo 5. Renderize e verifique o arquivo git

archives.render { "tree": "app", "cut": "v1.4.0" }
archives.verify { "tree": "app", "cut": "v1.4.0" }

Render escreve os commits da árvore e a tag do corte no arquivo; verify informa o status do arquivo e, quando houver, a primeira diferença. Na página do corte, um admin do workspace tem os mesmos botões Render e Verify, e cada resposta aparece literalmente: Rendered: tag <id>, Verify: <status>.

Passo 6. Defina o remoto

archives.set_remote { "tree": "app", "remote": "https://github.com/acme/app.git" }

O remoto é escrito https://github.com/<owner>/<repo>.git. Ele também é o campo Remote de cada repositório em Settings → Workspace → Source control. Defini-lo exige ser admin do workspace, "because the remote decides where the archive is published" (porque o remoto decide onde o arquivo é publicado).

Passo 7. Faça o push

archives.push { "tree": "app" }

"The push sends the remote only what it lacks, fast-forward only, as the instance's GitHub App, and refuses rather than move main backwards or move a tag." (O push envia ao remoto só o que falta, só com fast-forward, como a GitHub App da instância, e recusa em vez de mover main para trás ou mover uma tag.) Ele entra na fila como um job (Push queued as job <id>.). As recusas nomeiam a causa, por exemplo The tree <path> has no archive remote; set one with archives.set_remote, and nothing was pushed., ou uma que diz que o arquivo "has no rendered cut" (não tem corte renderizado). Uma recusa do GitHub volta como The remote refused <ref>: <reason>. com o motivo do próprio GitHub.

"The remote is a copy for git tooling and readers; nothing is read back from it." (O remoto é uma cópia para ferramentas git e leitores; nada é lido de volta dele.) O trabalho continua no Carbon Forge, e o próximo corte faz push de novo.

Passo 8. Leia o deploy de volta

"Once a cut is pushed, its deploy can be read back" (depois que um corte é enviado, o deploy dele pode ser lido de volta): archives.deploy_status responde as execuções de GitHub Actions do remoto para o commit do corte, no máximo 100, com um resumo, "and the record still takes nothing from the remote" (e o registro continua sem tirar nada do remoto). O índice de cortes marca cada árvore como pushed, tagged ou not rendered. Um webhook em cut.taken ou archive.pushed avisa um script de deploy sem polling.

O que a documentação deixa sem resposta

Um primeiro push para um repositório que já tem histórico. O push é só fast-forward e se recusa a mover main para trás; a documentação descreve uma reescrita de histórico opcional, mas não percorre o caso de um main existente e sem relação.
Hosts que não sejam o GitHub. Todo remoto na documentação é uma URL do GitHub.
Se uma implantação auto-hospedada pode usar a App do CarbonForge.dev ou precisa registrar a sua; a página de configurações nomeia as opções do operador, mas não essa escolha.

Corte uma versão no Carbon Forge e envie-a ao GitHub