Releases automatizados de plugins | EmDash CMS Everything

Los releases automatizados construyen y publican un plugin sandboxed cuando envías un tag de versión o inicias un workflow de GitHub Actions manualmente. Tu cuenta Atmosphere es propietaria del perfil del paquete y los registros de releases. GitHub identifica el workflow aprobado, y el servicio de releases verifica y publica el resultado sin almacenar credenciales de cuenta en el repositorio.

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

Prerrequisitos

Prepara lo siguiente antes de comenzar:

Un repositorio público de GitHub que contenga un plugin EmDash sandboxed.
Un emdash-plugin.jsonc válido con slug, publisher, license, un autor y un contacto de seguridad. Establece repo a la URL canónica de GitHub, o ingrésala durante la configuración interactiva.
Una versión en package.json, o en emdash-plugin.jsonc para un plugin solo de registro.
La cuenta Atmosphere nombrada por publisher.
Permiso para agregar un secreto de GitHub Actions al repositorio.
Un navegador que soporte passkeys. La aprobación de releases requiere verificación de usuario.

Ejecuta la verificación del manifiesto antes de configurar el workflow:

pnpm exec emdash-plugin validate

Configurar releases automatizados

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

La configuración pregunta cuándo un release necesita aprobación:
- Cuando aumentan los permisos del plugin es el valor predeterminado. Un release espera aprobación cuando su acceso declarado se expande en relación al último release.
- Para cada release requiere aprobación para cada versión.
La cuenta Atmosphere con sesión iniciada se convierte en el aprobador inicial. El perfil también vincula el paquete a la URL canónica del repositorio de GitHub y requiere procedencia verificable.

Ejecuta solo el paso del perfil cuando ya existe un archivo de workflow:
```
pnpm exec emdash-plugin profile setup
```
En una terminal no interactiva, pasa --yes para aceptar la política de aprobación predeterminada. Pasa --repository <https-url> cuando el manifiesto no contiene repo, y --confirmation always para requerir aprobación para cada release.
Revisa y haz commit del workflow generado.

El comando crea .github/workflows/emdash-release.yml. No envía el archivo y no reemplaza un workflow existente a menos que pases --force.

El workflow generado se ejecuta para tags de versión que coincidan con v* y mediante workflow_dispatch. Otorga contents: read, id-token: write y attestations: write; fija Actions de terceros a identificadores completos de commit; construye un bundle de plugin; crea procedencia de build de GitHub para esos bytes exactos; y pasa ambos archivos a la Action de release de EmDash.
Abre el panel del servicio de releases e inicia sesión con la misma cuenta Atmosphere.

Selecciona Authorize publishing. Tu proveedor de cuenta muestra el permiso delegado exacto. La concesión retenida puede crear registros de release de paquetes y subir blobs de paquetes o imágenes de listado. No puede crear o editar perfiles de paquetes, actualizar o eliminar releases, o escribir en otra colección.
Crea una invitación de workflow.

Ingresa el ID del plugin de emdash-plugin.jsonc, luego selecciona Create invitation. Agrega el valor de un solo uso al repositorio de GitHub como un secreto de Actions llamado EMDASH_CONNECTION_INVITATION.

La invitación es válida por 30 minutos y solo puede conectar el plugin nombrado. Crea una nueva invitación si expira antes de que el workflow la consuma.
Inicia el workflow de release.

Actualiza la versión del paquete antes de crear el tag de versión. Los siguientes comandos inician un release 1.2.3:
```
git tag v1.2.3
git push origin v1.2.3
```
También puedes seleccionar Run workflow en la página de GitHub Actions del repositorio.
Aprueba la conexión del workflow en su primera ejecución.

La Action escribe un enlace en el resumen del job de GitHub y espera. Abre el enlace y confirma el plugin, repositorio, archivo de workflow, branch o tag, y entorno.

Para una ejecución activada por tag, elige All version tags u Only this tag. Una solicitud activada por branch cubre solo esa branch. El servicio almacena los IDs del repositorio y propietario de GitHub, así como el ref seleccionado y el alcance del entorno. Las ejecuciones posteriores deben coincidir con esta política.
Aprueba el release cuando sea necesario.

Un release que expande permisos del plugin, o un perfil configurado para confirmación de 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 no tiene uno, revisa el cambio de permisos y aprueba o rechaza el release.

La configuración predeterminada de la Action retorna exitosamente cuando el release alcanza Awaiting approval. El workflow del servicio continúa esperando la decisión del navegador y publica después de la aprobación.

Qué verifica el servicio de releases

El servicio completa estas verificaciones antes de escribir un release:

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

La Action solicita un token OIDC fresco de GitHub para cada llamada al servicio. Los archivos de bundle y procedencia entran en almacenamiento transitorio privado solo después de que el workflow está autorizado. El servicio sube los bytes verificados del paquete e imagen al servidor de datos personal (PDS) del publicador, crea el registro de release allí y expone la procedencia verificada a través de una URL inmutable direccionada por suma de verificación.

Límites de autoridad

Cada credencial tiene un trabajo:

Credencial	Usada por	Autoridad
Sesión OAuth local del CLI	`emdash-plugin profile setup`	Crear o actualizar el perfil del paquete propiedad del publicador después de confirmación local.
Token OIDC de GitHub	Action de release	Identifica una ejecución de workflow de GitHub ante el servicio. No otorga acceso de escritura AT Protocol.
Delegación del servicio de releases	Servicio de releases	Crea registros de release de paquetes y sube los blobs requeridos.
Sesión de aplicación del publicador	Panel de releases	Autoriza conexiones de workflow y revoca publicación delegada.
Sesión del aprobador y passkey	Página de aprobación	Aprueba o rechaza una verificación de release vinculada a suma de verificación.
Identidad Cloudflare Access	Consola del operador del servicio	Opera el servicio alojado. No representa a un publicador o aprobador.

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

Comportamiento de la Action

El workflow generado usa la Action de apps/release-action. La Action acepta un bundle construido más procedencia Sigstore sin procesar, o un release-file de compatibilidad que contiene fuentes de artefactos HTTPS vinculadas por suma de verificación. No combines release-file con entradas de bundle o procedencia.

El workflow estándar generado proporciona estas entradas:

Entrada	Valor
`service-url`	Origen HTTPS del servicio de releases.
`publisher-did`	DID propietario del perfil del paquete y releases.
`connection-invitation`	`EMDASH_CONNECTION_INVITATION` en la primera conexión.
`bundle-file`	El tarball único producido por `emdash-plugin bundle`.
`provenance-file`	Salida `bundle-path` sin procesar de `actions/attest-build-provenance`.

La Action retorna estas salidas:

Salida	Significado
`connection-url`	URL del navegador para la aprobación del workflow en la primera ejecución.
`intent-id`	Identificador de intención de release.
`state`	Estado Published, terminal o `awaiting_approval`.
`approval-url`	URL del navegador cuando se requiere aprobación con passkey.
`release-uri`	URI AT del release publicado.
`release-cid`	CID del registro de release publicado.
`reason-code`	Razón estable para un intento terminal.

Consulta la referencia de la Action para entradas opcionales, workflows personalizados de fuente URL, controles de polling y comportamiento exacto de salida.

Resolución de problemas

`PACKAGE_PROFILE_REQUIRED`

El perfil del paquete falta, carece de configuración de release delegado, usa una URL de repositorio no canónica o nombra un repositorio diferente del workflow de GitHub.

Ejecuta la configuración del perfil localmente con la cuenta del publicador, luego inicia el workflow nuevamente:

pnpm exec emdash-plugin profile setup

Esta verificación se ejecuta antes de que el servicio acepte subidas de bundle o procedencia.

Repositorio público requerido

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

Invitación expirada o inválida

Crea otra invitación en el panel de releases y reemplaza EMDASH_CONNECTION_INVITATION. Inicia el workflow dentro de 30 minutos. Una invitación es de un solo uso y está limitada a un ID de plugin.

`WORKLOAD_NOT_ALLOWED`

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

`PROFILE_FETCH_FAILED`

El servicio no pudo verificar el perfil desde el PDS del publicador. Reintenta cuando el proveedor de cuenta esté disponible. Ejecuta emdash-plugin profile setup si el perfil fue eliminado o cambiado.

`POLL_TIMEOUT`

La Action alcanzó timeout-minutes antes de que la aprobación del workflow, aprobación del release o publicación se completara. Verifica el estado del intento en el panel de releases antes de reiniciar. Una re-ejecución de la misma ejecución de GitHub Actions reutiliza su clave de idempotencia.

Revocar publicación automatizada

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

Reconecta la publicación y aprueba el workflow nuevamente antes del próximo release automatizado.

Documentación relacionada

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