Releases automatizados de plugins | EmDash CMS Everything

Releases automatizados compilam e publicam um plugin em sandbox quando você faz push de uma tag de versão ou inicia manualmente um workflow do GitHub Actions. Sua conta Atmosphere é proprietária do perfil do pacote e dos registros de release. O GitHub identifica o workflow aprovado, e o serviço de release verifica e publica o resultado sem armazenar credenciais da conta no repositório.

Use emdash-plugin publish para um release iniciado a partir do seu computador. Use este guia quando o GitHub Actions deve compilar e publicar releases.

Pré-requisitos

Prepare o seguinte antes de começar:

Um repositório GitHub público contendo um plugin EmDash em sandbox.
Um emdash-plugin.jsonc válido com slug, publisher, license, um autor e um contato de segurança. Defina repo para a URL GitHub canônica, ou insira-a durante a configuração interativa.
Uma versão em package.json, ou em emdash-plugin.jsonc para um plugin somente registro.
A conta Atmosphere indicada por publisher.
Permissão para adicionar um secret do GitHub Actions ao repositório.
Um navegador que suporte passkeys. A aprovação de release requer verificação do usuário.

Execute a verificação do manifesto antes de configurar o workflow:

pnpm exec emdash-plugin validate

Configurar releases automatizados

Faça login no CLI do plugin com a conta Atmosphere proprietária do pacote.
```
pnpm exec emdash-plugin login alice.example.com
```
O CLI armazena esta sessão de publicação local fora do projeto. O GitHub Actions nunca a recebe.
Prepare o perfil do pacote e gere o workflow.
```
pnpm exec emdash-plugin release setup
```
O comando lê os metadados do pacote de emdash-plugin.jsonc. Se o perfil do pacote estiver ausente, oferece criá-lo. Se o perfil existir sem configurações de release delegado, oferece adicioná-las preservando os metadados existentes do pacote.

A configuração pergunta quando um release precisa de aprovação:
- Quando as permissões do plugin aumentam é o padrão. Um release aguarda aprovação quando seu acesso declarado se expande em relação ao último release.
- Para cada release requer aprovação para cada versão.
A conta Atmosphere conectada se torna o aprovador inicial. O perfil também vincula o pacote à URL canônica do repositório GitHub e requer procedência verificável.

Execute apenas a etapa do perfil quando um arquivo de workflow já existir:
```
pnpm exec emdash-plugin profile setup
```
Em um terminal não interativo, passe --yes para aceitar a política de aprovação padrão. Passe --repository <https-url> quando o manifesto não contiver repo, e --confirmation always para exigir aprovação para cada release.
Revise e faça commit do workflow gerado.

O comando cria .github/workflows/emdash-release.yml. Ele não faz push do arquivo e não substitui um workflow existente a menos que você passe --force.

O workflow gerado executa para tags de versão correspondentes a v* e via workflow_dispatch. Ele concede contents: read, id-token: write e attestations: write; fixa Actions de terceiros a identificadores de commit completos; compila um bundle de plugin; cria procedência de build do GitHub para esses bytes exatos; e passa ambos os arquivos para a Action de release do EmDash.
Abra o painel do serviço de release e faça login com a mesma conta Atmosphere.

Selecione Authorize publishing. Seu provedor de conta mostra a permissão delegada exata. A concessão retida pode criar registros de release de pacote e fazer upload de blobs de pacote ou imagem de listagem. Não pode criar ou editar perfis de pacote, atualizar ou excluir releases, ou escrever em outra coleção.
Crie um convite de workflow.

Insira o ID do plugin de emdash-plugin.jsonc, depois selecione Create invitation. Adicione o valor de uso único ao repositório GitHub como um secret do Actions chamado EMDASH_CONNECTION_INVITATION.

O convite é válido por 30 minutos e pode conectar apenas o plugin indicado. Crie um novo convite se expirar antes que o workflow o consuma.
Inicie o workflow de release.

Atualize a versão do pacote antes de criar a tag de versão. Os seguintes comandos iniciam um release 1.2.3:
```
git tag v1.2.3
git push origin v1.2.3
```
Você também pode selecionar Run workflow na página do GitHub Actions do repositório.
Aprove a conexão do workflow na primeira execução.

A Action escreve um link no resumo do job do GitHub e aguarda. Abra o link e confirme o plugin, repositório, arquivo de workflow, branch ou tag, e ambiente.

Para uma execução disparada por tag, escolha All version tags ou Only this tag. Uma solicitação disparada por branch cobre apenas essa branch. O serviço armazena os IDs do repositório e proprietário do GitHub, bem como o ref e escopo de ambiente selecionados. Execuções posteriores devem corresponder a esta política.
Aprove o release quando necessário.

Um release que expande permissões do plugin, ou um perfil configurado para confirmação a cada release, entra em Awaiting approval. Abra a URL de aprovação da saída da Action ou do painel de releases. Registre uma passkey se a conta aprovadora ainda não tiver uma, revise a mudança de permissão e aprove ou rejeite o release.

A configuração padrão da Action retorna com sucesso quando o release atinge Awaiting approval. O workflow do serviço continua aguardando a decisão do navegador e publica após a aprovação.

O que o serviço de release verifica

O serviço completa estas verificações antes de escrever um release:

O token GitHub OpenID Connect (OIDC) nomeia um repositório, proprietário, workflow, ref, ambiente, commit, execução e runner hospedado no GitHub autorizados.
O perfil do pacote existe, é assinado pelo publicador, contém configurações de release delegado e nomeia o mesmo repositório GitHub canônico.
O pacote e a versão solicitados correspondem ao bundle de plugin compilado.
O checksum do pacote corresponde aos bytes enviados.
A procedência do GitHub cobre o mesmo bundle, repositório, workflow, commit e execução.
O acesso declarado do registro de release corresponde ao manifesto do bundle.
O registro de versão ainda não existe.
Qualquer aprovação de passkey necessária cobre o resultado de verificação exato e a revisão atual do perfil.

A Action solicita um token OIDC do GitHub novo para cada chamada ao serviço. Arquivos de bundle e procedência entram em armazenamento transitório privado somente após o workflow ser autorizado. O serviço faz upload dos bytes verificados de pacote e imagem para o servidor de dados pessoal (PDS) do publicador, cria o registro de release lá e expõe a procedência verificada através de uma URL imutável endereçada por checksum.

Limites de autoridade

Cada credencial tem uma função:

Credencial	Usada por	Autoridade
Sessão OAuth local do CLI	`emdash-plugin profile setup`	Criar ou atualizar o perfil do pacote de propriedade do publicador após confirmação local.
Token OIDC do GitHub	Action de release	Identificar uma execução de workflow do GitHub ao serviço. Não concede acesso de escrita AT Protocol.
Delegação do serviço de release	Serviço de release	Criar registros de release de pacote e fazer upload dos blobs necessários.
Sessão do aplicativo do publicador	Painel de releases	Autorizar conexões de workflow e revogar publicação delegada.
Sessão e passkey do aprovador	Página de aprovação	Aprovar ou rejeitar uma verificação de release vinculada a checksum.
Identidade Cloudflare Access	Console do operador do serviço	Operar o serviço hospedado. Não representa um publicador ou aprovador.

O serviço armazena os estados do publicador e aprovador separadamente. Fazer login para ver seus releases não concede acesso de operador, e uma identidade de operador não pode aprovar um release como publicador.

Comportamento da Action

O workflow gerado usa a Action de apps/release-action. A Action aceita um bundle compilado mais procedência Sigstore bruta, ou um release-file de compatibilidade contendo fontes de artefatos HTTPS vinculadas a checksum. Não combine release-file com entradas de bundle ou procedência.

O workflow padrão gerado fornece estas entradas:

Entrada	Valor
`service-url`	Origem HTTPS do serviço de release.
`publisher-did`	DID proprietário do perfil do pacote e releases.
`connection-invitation`	`EMDASH_CONNECTION_INVITATION` na primeira conexão.
`bundle-file`	O tarball único produzido por `emdash-plugin bundle`.
`provenance-file`	Saída bruta `bundle-path` de `actions/attest-build-provenance`.

A Action retorna estas saídas:

Saída	Significado
`connection-url`	URL do navegador para aprovação do workflow na primeira execução.
`intent-id`	Identificador de intenção de release.
`state`	Estado Published, terminal ou `awaiting_approval`.
`approval-url`	URL do navegador quando aprovação de passkey é necessária.
`release-uri`	URI AT do release publicado.
`release-cid`	CID do registro de release publicado.
`reason-code`	Razão estável para uma intenção terminal.

Consulte a referência da Action para entradas opcionais, workflows de fonte URL personalizada, controles de polling e comportamento exato de saída.

Solução de problemas

`PACKAGE_PROFILE_REQUIRED`

O perfil do pacote está ausente, faltam configurações de release delegado, usa uma URL de repositório não canônica ou nomeia um repositório diferente do workflow do GitHub.

Execute a configuração do perfil localmente com a conta do publicador, depois reinicie o workflow:

pnpm exec emdash-plugin profile setup

Esta verificação é executada antes que o serviço aceite uploads de bundle ou procedência.

Repositório público necessário

O GitHub usa uma raiz de confiança Sigstore privada para repositórios privados e internos. O verificador de release atualmente confia apenas na procedência pública do GitHub. Mova o workflow de release para um repositório público ou publique localmente com emdash-plugin publish.

Convite expirado ou inválido

Crie outro convite no painel de releases e substitua EMDASH_CONNECTION_INVITATION. Inicie o workflow dentro de 30 minutos. Um convite é de uso único e limitado a um ID de plugin.

`WORKLOAD_NOT_ALLOWED`

O repositório GitHub, proprietário, arquivo de workflow, ref ou ambiente não corresponde à política de workflow aprovada. Abra o painel de releases e aprove uma nova conexão de workflow com o escopo pretendido.

`PROFILE_FETCH_FAILED`

O serviço não conseguiu verificar o perfil do PDS do publicador. Tente novamente quando o provedor de conta estiver disponível. Execute emdash-plugin profile setup se o perfil foi removido ou alterado.

`POLL_TIMEOUT`

A Action atingiu timeout-minutes antes que a aprovação do workflow, aprovação do release ou publicação fosse concluída. Verifique o estado da intenção no painel de releases antes de reexecutar. Uma reexecução da mesma execução do GitHub Actions reutiliza sua chave de idempotência.

Revogar publicação automatizada

Selecione Turn off automated publishing no painel de releases. A revogação limpa a delegação de release retida. Perfis de pacotes existentes, releases, rótulos de moderação, plugins instalados e o login do painel não mudam.

Reconecte a publicação e aprove o workflow novamente antes do próximo release automatizado.

Documentação relacionada

Bundling and publishing cobre publicação local e validação de bundle.
The plugin manifest define metadados do pacote e acesso declarado.
Capabilities and security explica as permissões revisadas durante a aprovação de release e instalação.
The plugin registry explica descoberta, moderação e verificação de instalação.