Publicaciones automatizadas de plugins

Las publicaciones automatizadas construyen y publican un plugin sandboxed cuando envías una etiqueta de versión o inicias un flujo de trabajo de GitHub Actions manualmente. Tu cuenta de Atmosphere sigue siendo propietaria del perfil del paquete y de los registros de release. GitHub identifica el flujo de trabajo aprobado, y el servicio de releases verifica la compilación y escribe el release mediante una delegación estrecha. El repositorio no almacena una credencial de cuenta de Atmosphere.

Usa emdash-plugin publish para un release iniciado desde tu ordenador. Usa esta guía cuando GitHub Actions deba construir y publicar releases.

Requisitos previos

Prepara lo siguiente antes de empezar:

Un repositorio público de GitHub que contenga un plugin sandboxed de EmDash.
@emdash-cms/plugin-cli instalado como dependencia de desarrollo. Los plugins creados con la CLI ya lo incluyen.
Un emdash-plugin.jsonc válido con slug, publisher, license, un autor y un contacto de seguridad. Establece repo en la URL canónica de GitHub, o confirma el remoto de GitHub detectado durante la configuración interactiva.
Una versión en package.json, o en emdash-plugin.jsonc para un plugin solo de registro.
La cuenta de Atmosphere nombrada por publisher.
Un navegador que admita passkeys. La aprobación de releases requiere verificación de usuario.

Ejecuta la comprobación del manifiesto antes de configurar el flujo de trabajo:

pnpm exec emdash-plugin validate

Configurar publicaciones automatizadas

Inicia sesión en la CLI del plugin con la cuenta de Atmosphere propietaria del paquete.
```
pnpm exec emdash-plugin login alice.example.com
```
La CLI almacena esta sesión local de publicación fuera del proyecto. GitHub Actions nunca la recibe.
Prepara el perfil del paquete y genera el flujo de trabajo desde el directorio del plugin.
```
pnpm exec emdash-plugin release setup
```
El comando lee los metadatos del paquete desde emdash-plugin.jsonc. Si falta el perfil del paquete, ofrece crearlo. Si el perfil existe sin ajustes de delegated-release, ofrece añadirlos preservando los metadatos existentes del paquete.

En un monorepo, ejecuta el comando dentro del paquete del plugin o pasa --dir <plugin-directory>. Si el manifiesto no contiene repo, la configuración detecta el remoto origin de GitHub y rellena previamente el mensaje del repositorio.

La configuración pregunta cuándo un release necesita aprobación:
- When plugin permissions increase es el valor predeterminado. Un release espera aprobación cuando su acceso declarado se amplía respecto al último release.
- For every release requiere aprobación para cada versión.
La configuración también pregunta si los releases requieren provenance verificable. Require provenance es el valor predeterminado para publicaciones automatizadas. Elige Allow releases without provenance solo cuando el mismo perfil deba aceptar también releases publicados directamente desde un entorno local de confianza.

La cuenta de Atmosphere con la que iniciaste sesión se convierte en el aprobador inicial. El perfil vincula el paquete a la URL canónica del repositorio de GitHub y registra la política de provenance seleccionada.

Ejecuta solo el paso del perfil cuando ya exista un archivo de flujo de trabajo:
```
pnpm exec emdash-plugin profile setup
```
Tras publicar el perfil del paquete, este comando muestra los comandos de release manual y de GitHub Actions.

En un terminal no interactivo, pasa --yes para aceptar las políticas predeterminadas. Pasa --repository <https-url> cuando ni el manifiesto ni el remoto de Git proporcionen el repositorio, --provenance optional para permitir releases sin provenance, y --confirmation always para exigir aprobación en cada release.
Revisa y confirma el flujo de trabajo generado.

El comando crea .github/workflows/emdash-release.yml. No envía el archivo ni reemplaza un flujo de trabajo existente a menos que pases --force.

Si el repositorio contiene .changeset/config.json, la configuración interactiva ofrece Follow Changesets releases. Cuando Changesets publica un paquete que contiene emdash-plugin.jsonc, el flujo de trabajo reutilizable de EmDash publica la misma versión. Conéctalo al flujo de trabajo de Changesets existente como se describe más abajo. De lo contrario, el flujo de trabajo generado se ejecuta para etiquetas de paquete que coincidan con <slug>@<version>. Ambas variantes admiten ejecuciones manuales y se pueden seleccionar explícitamente con --trigger changesets|tags|manual.

El flujo de trabajo concede a cada job solo los permisos contents, id-token y attestations requeridos; fija las Actions de terceros a identificadores de commit completos; ejecuta la versión exacta de la CLI del plugin que generó el archivo; resuelve cada paquete desde su manifiesto; construye un bundle del plugin; crea provenance de build de GitHub para esos bytes exactos; y pasa ambos archivos a la Action de release de EmDash.

El flujo de trabajo vive en la raíz del repositorio y es compartido por cada paquete de plugin de ese repositorio. Ejecutar release setup desde un paquete anidado sigue escribiendo .github/workflows/emdash-release.yml en la raíz.
Abre el panel del servicio de releases e inicia sesión con la misma cuenta de Atmosphere.

Selecciona Authorize publishing. Tu proveedor de cuenta muestra el permiso delegado exacto. La concesión retenida puede crear registros de release de paquete y subir blobs de paquete o de imagen de listado. No puede crear ni editar perfiles de paquete, actualizar o eliminar releases, ni escribir en otra colección.
Inicia el flujo de trabajo de release.

Con Changesets, fusiona la pull request de versión y deja que su job de publicación termine. La Action de Changesets pasa los paquetes que publicó al flujo de trabajo reutilizable de EmDash. Los paquetes npm ordinarios se ignoran; los paquetes que contienen emdash-plugin.jsonc publican la misma versión en EmDash.

Con el disparador de etiqueta de paquete, actualiza la versión del paquete antes de crear la etiqueta de versión. Los siguientes comandos inician un release 1.2.3:
```
git tag gallery@1.2.3
git push origin gallery@1.2.3
```
También puedes seleccionar Run workflow en la página de GitHub Actions del repositorio.
Aprueba cada alcance de ref del repositorio en su primera ejecución.

El servicio verifica que el perfil del paquete iniciador nombre el repositorio de GitHub antes de crear una solicitud de conexión. La Action escribe un enlace en el resumen del job de GitHub y espera. Abre el enlace y confirma el repositorio, el archivo de flujo de trabajo, la rama o etiqueta, y el entorno.

Para una ejecución disparada por etiqueta, elige All package version tags o Only this tag. Una ejecución manual solicita aprobación la primera vez que se usa su rama. Confirmar otro alcance de etiqueta o rama lo añade a la conexión del repositorio sin eliminar los alcances existentes. El servicio almacena los ID del repositorio y del propietario de GitHub, así como los refs y entornos aprobados. Los paquetes posteriores reutilizan estos alcances solo cuando sus perfiles firmados nombran el mismo repositorio.

Las aprobaciones de paquete creadas por flujos de trabajo generados más antiguos siguen limitadas a sus paquetes originales. El primer paquete o ref no coincidente solicita una conexión de repositorio; el servicio no amplía automáticamente una aprobación de paquete existente.
Aprueba el release cuando sea necesario.

Un release que amplía los permisos del plugin, o un perfil configurado para confirmación en cada release, entra en Awaiting approval. Abre la URL de aprobación desde la salida de la Action o el panel de releases. Registra un passkey si la cuenta aprobadora aún no tiene uno, revisa el cambio de permisos y aprueba o rechaza el release.

La configuración predeterminada de la Action devuelve éxito cuando el release alcanza Awaiting approval. El flujo de trabajo del servicio sigue esperando la decisión del navegador y publica tras la aprobación.

Conectar un flujo de trabajo de Changesets

El .github/workflows/emdash-release.yml generado acepta el JSON de paquetes publicados de la Action de Changesets mediante workflow_call. Añade una salida al job de Changesets existente y luego llama al flujo de trabajo de EmDash desde un job dependiente. Sustituye release y changesets cuando el job o paso existente use otro ID.

Changesets Action v2 usa la salida published-packages. Añade la siguiente salida de job y el llamador a un flujo de trabajo 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 la salida de paso en camel-case publishedPackages. Usa esta expresión para un flujo de trabajo 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

Mantén a Changesets responsable de su pull request de versión y de la publicación del paquete. El llamador de EmDash se ejecuta solo cuando Changesets informa published: true. Para paquetes privados solo de EmDash, establece tanto privatePackages.version como privatePackages.tag en true en .changeset/config.json. Añade aplicaciones privadas no relacionadas y fixtures de prueba a ignore.

Añadir otro paquete

Prepara el perfil del paquete desde su directorio de origen. Se reutilizan el flujo de trabajo raíz existente y la conexión del repositorio:

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

Con Changesets, añade el paquete a un changeset y fusiona su pull request de versión. Con el disparador de etiqueta de paquete, actualiza la versión del paquete y envía su etiqueta:

git tag comments@1.0.0
git push origin comments@1.0.0

El flujo de trabajo resuelve comments a un emdash-plugin.jsonc, comprueba la versión seleccionada y verifica que el perfil firmado nombre el repositorio conectado antes de aceptar subidas de artefactos. Los ID de paquete duplicados y las discrepancias de versión fallan antes de la attestation.

Qué verifica el servicio de releases

El servicio completa estas comprobaciones antes de escribir un release:

El token OpenID Connect (OIDC) de GitHub nombra un repositorio, propietario, flujo de trabajo, ref, entorno, commit, ejecución y runner alojado en GitHub autorizados.
El perfil del paquete existe, está firmado por el publisher, contiene ajustes de delegated-release y nombra el mismo repositorio canónico de GitHub.
El paquete y la versión solicitados coinciden con el bundle del plugin compilado.
La suma de comprobación del paquete coincide con los bytes subidos.
La provenance de GitHub cubre el mismo bundle, repositorio, flujo de trabajo, commit y ejecución.
El acceso declarado del registro de release coincide con el manifiesto del bundle.
El registro de versión aún no existe.
Cualquier aprobación por passkey requerida cubre el resultado exacto de verificación y la revisión actual del perfil.

La Action solicita un token OIDC de GitHub nuevo para cada llamada al servicio. Los archivos de bundle y provenance entran en almacenamiento transitorio privado solo después de que el flujo de trabajo esté autorizado. El servicio sube los bytes verificados de paquete e imagen al servidor de datos personales (PDS) del publisher, crea allí el registro de release y expone la provenance verificada mediante una URL inmutable dirigida por suma de comprobación.

Límites de autoridad

Cada credencial tiene un trabajo:

Credential	Used by	Authority
Local CLI OAuth session	`emdash-plugin profile setup`	Create or update the publisher-owned package profile after local confirmation.
GitHub OIDC token	Release Action	Identify one GitHub workflow run to the service. It grants no AT Protocol write access.
Release-service delegation	Release service	Create package release records and upload the required blobs.
Publisher application session	Release dashboard	Authorise workflow connections and revoke delegated publishing.
Approver session and passkey	Approval page	Approve or reject one checksum-bound release verification.
Cloudflare Access identity	Service operator console	Operate the hosted service. It does not represent a publisher or approver.

El servicio almacena el estado del publisher y del aprobador por separado. Iniciar sesión para ver tus releases no concede acceso de operador, y una identidad de operador no puede aprobar un release como publisher.

Comportamiento de la Action

El flujo de trabajo generado usa la Action de apps/release-action. La Action acepta un bundle compilado más provenance Sigstore en bruto, o un release-file de compatibilidad que contiene fuentes de artefactos HTTPS vinculadas a suma de comprobación. No combines release-file con entradas de bundle o provenance.

El flujo de trabajo generado estándar suministra estas entradas. Se muestran aquí para que puedas revisar el archivo generado sin tener que inferir qué autoriza cada valor:

Input	Value
`service-url`	Release-service HTTPS origin.
`publisher-did`	DID that owns the package profile and releases.
`bundle-file`	The single tarball produced by `emdash-plugin release prepare`.
`provenance-file`	Raw `bundle-path` output from `actions/attest-build-provenance`.

La Action devuelve estas salidas:

Output	Meaning
`connection-url`	Browser URL for first-run workflow approval.
`intent-id`	Release intent identifier.
`state`	Published, terminal, or `awaiting_approval` state.
`approval-url`	Browser URL when passkey approval is required.
`release-uri`	Published release AT URI.
`release-cid`	Published release record CID.
`reason-code`	Stable reason for a terminal intent.

Consulta la referencia de la Action para entradas opcionales, flujos de trabajo con fuentes URL personalizadas, controles de sondeo y el comportamiento exacto de las salidas.

Solución de problemas

`PACKAGE_PROFILE_REQUIRED`

Falta el perfil del paquete, carece de ajustes de delegated-release, usa una URL de repositorio no canónica o nombra un repositorio distinto del flujo de trabajo de GitHub.

Ejecuta la configuración del perfil localmente con la cuenta del publisher y vuelve a iniciar el flujo de trabajo:

pnpm exec emdash-plugin profile setup

Esta comprobación se ejecuta antes de que el servicio acepte subidas de bundle o provenance.

Se requiere un repositorio público

GitHub usa una raíz de confianza Sigstore privada para repositorios privados e internos. El verificador de releases actualmente confía solo en provenance pública de GitHub. Mueve el flujo de trabajo de release a un repositorio público o publica localmente con emdash-plugin publish.

`WORKLOAD_NOT_ALLOWED`

El repositorio, propietario, archivo de flujo de trabajo, ref o entorno de GitHub no coincide con la política de flujo de trabajo aprobada. Abre el panel de releases y aprueba una nueva conexión de flujo de trabajo con el alcance previsto.

`PROFILE_FETCH_FAILED`

El servicio no pudo verificar el perfil desde el PDS del publisher. Reintenta cuando el proveedor de la cuenta esté disponible. Ejecuta emdash-plugin profile setup si el perfil se eliminó o cambió.

`POLL_TIMEOUT`

La Action alcanzó timeout-minutes antes de que se completaran la aprobación del flujo de trabajo, la aprobación del release o la publicación. Comprueba el estado del intent en el panel de releases antes de volver a ejecutarlo. Una nueva ejecución de la misma ejecución de GitHub Actions reutiliza su clave de idempotencia.

Revocar la publicación automatizada

Selecciona Turn off automated publishing en el panel de releases. La revocación borra la delegación de release retenida. Los perfiles de paquete existentes, releases, etiquetas de moderación, plugins instalados y el inicio de sesión del panel no cambian.

Vuelve a conectar la publicación y aprueba el flujo de trabajo de nuevo antes del siguiente release automatizado.

Documentación relacionada

Bundling and publishing cubre la publicación local y la validación de bundles.
The plugin manifest define los metadatos del paquete y el acceso declarado.
Capabilities and security explica los permisos revisados durante la aprobación del release y la instalación.
The plugin registry explica el descubrimiento, la moderación y la verificación de la instalación.