Releases automatizados de plugins

Releases automatizados compilam e publicam um plugin sandboxed quando você envia uma tag de versão ou inicia um workflow do GitHub Actions manualmente. Sua conta Atmosphere continua proprietária do perfil do pacote e dos registros de release. O GitHub identifica o workflow aprovado, e o serviço de release verifica a build e grava o release por meio de uma delegação restrita. O repositório não armazena uma credencial de conta Atmosphere.

Use emdash-plugin publish para um release iniciado 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 sandboxed.
• @emdash-cms/plugin-cli instalado como dependência de desenvolvimento. Plugins criados com a CLI já o incluem.
• Um emdash-plugin.jsonc válido com slug, publisher, license, um autor e um contato de segurança. Defina repo como a URL canônica do GitHub, ou confirme o remoto GitHub detectado durante a configuração interativa.
• Uma versão em package.json, ou em emdash-plugin.jsonc para um plugin somente de registro.
• A conta Atmosphere nomeada por publisher.
• Um navegador que suporte passkeys. A aprovação de release exige verificação do usuário.

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

pnpm exec emdash-plugin validate

Configurar releases automatizados

Conectar um workflow Changesets

O .github/workflows/emdash-release.yml gerado aceita o JSON de pacotes publicados da Action Changesets por meio de workflow_call. Adicione uma saída ao job Changesets existente e, em seguida, chame o workflow EmDash a partir de um job dependente. Substitua release e changesets quando o job ou passo existente usar outro ID.

Changesets Action v2 usa a saída published-packages. Adicione a seguinte saída de job e o chamador a um workflow que use Changesets CLI v3:

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs['published-packages'] }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

Changesets Action v1 usa a saída do passo em camel-case publishedPackages. Use esta expressão para um workflow que use Changesets CLI v2:

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs.publishedPackages }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

Mantenha o Changesets responsável pelo pull request de versão e pela publicação do pacote. O chamador EmDash é executado somente quando o Changesets reporta published: true. Para pacotes privados somente EmDash, defina privatePackages.version e privatePackages.tag como true em .changeset/config.json. Adicione aplicações privadas não relacionadas e fixtures de teste a ignore.

Adicionar outro pacote

Prepare o perfil do pacote a partir do seu diretório de origem. O workflow raiz existente e a conexão do repositório são reutilizados:

pnpm exec emdash-plugin profile setup --dir packages/comments

Com Changesets, adicione o pacote a um changeset e faça o merge do pull request de versão. Com o gatilho de tag de pacote, atualize a versão do pacote e envie sua tag:

git tag comments@1.0.0
git push origin comments@1.0.0

O workflow resolve comments para um emdash-plugin.jsonc, verifica a versão selecionada e confirma que o perfil assinado nomeia o repositório conectado antes de aceitar uploads de artefatos. IDs de pacote duplicados e divergências de versão falham antes da attestation.

O que o serviço de release verifica

O serviço conclui estas verificações antes de gravar um release:

1. O token OpenID Connect (OIDC) do GitHub nomeia um repositório, proprietário, workflow, ref, ambiente, commit, execução e runner hospedado no GitHub autorizados.
2. O perfil do pacote existe, está assinado pelo publisher, contém configurações de delegated-release e nomeia o mesmo repositório GitHub canônico.
3. O pacote e a versão solicitados correspondem ao bundle do plugin compilado.
4. A checksum do pacote corresponde aos bytes enviados.
5. A provenance do GitHub cobre o mesmo bundle, repositório, workflow, commit e execução.
6. O acesso declarado do registro de release corresponde ao manifesto do bundle.
7. O registro de versão ainda não existe.
8. Qualquer aprovação por passkey necessária cobre o resultado exato da verificação 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 provenance entram em armazenamento transitório privado somente após a autorização do workflow. O serviço envia bytes verificados de pacote e imagem para o personal data server (PDS) do publisher, cria o registro de release lá e expõe a provenance verificada por meio de uma URL imutável endereçada por checksum.

Limites de autoridade

Cada credencial tem uma função:

O serviço armazena o estado do publisher e do aprovador separadamente. Entrar para ver seus releases não concede acesso de operador, e uma identidade de operador não pode aprovar um release como publisher.

Comportamento da Action

O workflow gerado usa a Action de apps/release-action. A Action aceita um bundle compilado mais provenance 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 provenance.

O workflow gerado padrão fornece estas entradas. Elas são mostradas aqui para que você possa revisar o arquivo gerado sem precisar inferir o que cada valor autoriza:

A Action retorna estas saídas:

Consulte a referência da Action para entradas opcionais, workflows com fontes URL personalizadas, controles de polling e o comportamento exato das saídas.

Solução de problemas

PACKAGE_PROFILE_REQUIRED

O perfil do pacote está ausente, não tem configurações de delegated-release, 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 publisher e inicie o workflow novamente:

pnpm exec emdash-plugin profile setup

Esta verificação é executada antes de o serviço aceitar uploads de bundle ou provenance.

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 em provenance pública do GitHub. Mova o workflow de release para um repositório público ou publique localmente com emdash-plugin publish.

WORKLOAD_NOT_ALLOWED

O repositório, proprietário, arquivo de workflow, ref ou ambiente do GitHub 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 pôde verificar o perfil a partir do PDS do publisher. Tente novamente quando o provedor da 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, a aprovação do release ou a publicação fossem concluídas. Verifique o estado do intent no painel de releases antes de executar novamente. Uma nova execução da mesma execução do GitHub Actions reutiliza sua chave de idempotência.

Revogar a publicação automatizada

Selecione Turn off automated publishing no painel de releases. A revogação limpa a delegação de release retida. Perfis de pacote 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 bundles.
• The plugin manifest define metadados do pacote e acesso declarado.
• Capabilities and security explica as permissões revisadas durante a aprovação do release e a instalação.
• The plugin registry explica descoberta, moderação e verificação da instalação.