Capgo Limpieza de Pull Request Preview API Key

Eliminar una vista previa de pull request parece un trabajo de un solo comando. Con Capgo, hay un detalle: debes salir de una vista previa activa antes de eliminarla y luego borrar sus bundles por ID. Crearemos un flujo de limpieza seguro con una clave API restringida, consulta de vistas previas, manejo de resets, eliminación de bundles y automatización de CI.

Tabla de contenidos

• Paso 1: Crea una clave Capgo API restringida para la limpieza de previews
• Paso 2: Identifica la preview del pull request y sus bundle IDs
• Paso 3: Sal de la preview activa antes de limpiar
• Paso 4: Elimina los bundles de preview por ID con la clave API
• Paso 5: Automatiza la limpieza al cerrar un pull request
• Paso 6: Verifica la limpieza y protege los rollouts frente a borrados accidentales
• FAQ
• Conclusión

Paso 1: Crea una clave Capgo API restringida para la limpieza de previews

El primer paso en el flujo de limpieza de previews de pull requests de Capgo es crear una clave que solo pueda realizar las tareas necesarias para tu trabajo de CI.

No uses una clave amplia de la organización en un workflow de pull request. Un pull request puede provenir de una rama que aún no ha ganado confianza. El workflow también podría imprimir un comando o valor de entorno durante una ejecución fallida. Una clave restringida limita el daño si eso ocurre.

En Capgo, empieza con una clave de App Preview para el trabajo de previsualización. La clave debe estar vinculada a la app o al ámbito de previsualización que gestiona tu trabajo. Si tu equipo usa control de acceso basado en roles, limita la clave a apps seleccionadas en lugar de otorgar acceso a toda la organización. Capgo documenta esas opciones de claves de previsualización en su API key settings for web app workflows.

Almacena el secreto en el almacén de secretos cifrados de tu proveedor de CI. Dale un nombre que indique su función, comoCAPGO_PREVIEW_CLEANUP_KEY. No lo coloques en un archivo de workflow, un script de shell, un comentario de pull request ni en un log generado.

Pasa la clave al proceso de limpieza a través de una variable de entorno. Tu script debe fallar si la variable falta. Un fallback silencioso es peligroso porque puede convertir un trabajo de limpieza en una solicitud sin autenticación, o tentarte a pegar una clave en la línea de comandos.

if [ -z "$CAPGO_PREVIEW_CLEANUP_KEY" ]; then echo "Missing preview cleanup key" exit 1
fi

Mantén esta clave separada de la clave usada para publicar bundles de producción. El trabajo de publicación puede necesitar subir un release. El trabajo de limpieza solo necesita eliminar recursos de previsualización. Claves separadas facilitan la revisión y reducen la probabilidad de que una acción de borrado llegue a un canal de producción.

Usa el mismo secreto en un entorno protegido cuando sea posible. Exige aprobación antes de que un trabajo pueda tocar canales compartidos. Para previsualizaciones de pull request ordinarias, el trabajo debe operar en un canal temporal y nada más.

Conclusión clave: Usa una clave de App Preview dedicada, limita su ámbito de app y guárdala en secretos cifrados de CI.

Antes de continuar, prueba la clave con una acción de lectura inofensiva. Confirma que el job puede ver la app prevista, pero no puede acceder a una app no relacionada ni a un workflow de producción. Los detalles exactos de la solicitud para la limpieza no están completamente publicados, así que mantén tu primera prueba pequeña e inspecciona la guía de soporte de SDK o Capgo antes de añadir llamadas de eliminación.

Paso 2: Identifica la preview del pull request y sus bundle IDs

La clave de limpieza de vista previa de pull request de Capgo API solo es útil cuando tu job sabe qué IDs de vista previa y bundle posee.

Usa una regla de nomenclatura estable para los canales de vista previa. Un patrón común es el nombre del repositorio más el número del pull request. El punto clave es la consistencia. Tu job de limpieza debe reconstruir el mismo identificador después de que se cierre el pull request.

Guarda el nombre del canal de vista previa cuando se cree la vista previa. Puedes colocarlo en la salida del workflow, en una comprobación del pull request o en un pequeño fragmento de metadatos del job. No dependas de un nombre de visualización que una persona podría cambiar en el dashboard.

A continuación, lista los bundles vinculados a esa vista previa. La acción Delete Bundle de Capgo requiere IDs de bundle. La documentación de origen apunta a una llamada de lista para recuperar todos los IDs de bundle disponibles antes de la eliminación. Trata esa lista como la fuente de verdad. Nunca adivines un ID a partir de un nombre de archivo, hash de commit o nombre de rama.

Filtra los registros devueltos por el canal de preview u otro valor que controle tu workflow. Luego, conserva el ID exacto de cada bundle coincidente. Si la lista está vacía, marca la limpieza como completada. Un resultado vacío no es un fallo a menos que tu workflow esperara que existiera una preview.

Registra también el SHA del commit que generó cada preview. Esto te da una segunda comprobación antes de eliminar. Si el nombre del canal coincide pero el commit no, detente y pide una revisión. Esa pequeña pausa puede evitar una condición de carrera en la que se está construyendo una nueva preview mientras se ejecuta un trabajo de limpieza antiguo.

No elimines mientras un trabajo de publicación siga ejecutándose. Añade una dependencia entre los workflows de build de preview y de limpieza, o usa un lock vinculado al número de pull request. El trabajo de limpieza solo debe iniciar después del evento de cierre y de que haya terminado cualquier subida de preview pendiente.

La API pública de Capgo cubre recursos como canales y bundles mediante solicitudes HTTP autenticadas, pero las acciones de limpieza aún requieren una verificación cuidadosa en tu proyecto. La Resumen de la API pública de Capgo es el lugar adecuado para confirmar el modelo de recursos actual antes de escribir un wrapper.

A estas alturas, deberías tener un identificador de preview, una lista de IDs de bundle exactos y el SHA del commit asociado a cada registro. Si falta alguno de esos valores, detente aquí. Limpiar sin comprobaciones de propiedad es pura conjetura.

Paso 3: Sal de la preview activa antes de limpiar

No se puede eliminar una preview activa hasta que la app deje de usarla o llames aresetPreview. Este es el detalle clave en el flujo de limpieza de previews de pull request de Capgo.

Piensa en la preview activa como la versión seleccionada actualmente por la app. Eliminar primero el registro en el servidor dejaría a la app apuntando a algo que ya no existe. Capgo bloquea ese cambio de estado, por lo que tu job de limpieza debe restablecer el estado de preview de la app antes de eliminar la preview.

Primero, comprueba si la preview sigue activa. Si es así, mueve la app a un canal seguro o usa la acción de reset del updater. La elección correcta depende de cómo esté configurada tu app de prueba. Una app de prueba desechable puede volver a su canal por defecto, mientras que una app compartida podría necesitar un canal de staging dedicado.

UsaresetPreviewcuando sea necesario limpiar el estado de la preview directamente. Mantén esta llamada vinculada al mismo pull request y a la misma app que creó la preview. Un script de limpieza nunca debe resetear un dispositivo de producción o un canal de release compartido solo porque el nombre del canal coincida.

Aquí tienes una regla de orden útil:

• Confirma que el pull request está cerrado.
• Confirma que no haya ningún upload de preview en curso.
• Sal de la preview activa o llama aresetPreview.
• Espera a que termine ese cambio de estado.
• Solo entonces llama a Delete Preview.

No consideres una respuesta HTTP exitosa del request de reset como prueba de que la app ya cambió de estado en todos los dispositivos. Un dispositivo puede buscar actualizaciones más tarde. Tu limpieza del lado del servidor puede continuar una vez que la asignación de la preview se haya limpiado según la respuesta de API, pero mantén el comportamiento del dispositivo separado de la eliminación de recursos.

Capgo permite el control de rollout basado en canales, lo que facilita razonar sobre esta separación. Un canal es una ruta con nombre que indica a la app qué stream de updates debe seguir. Tu canal de preview nunca debe ser el mismo que usan los dispositivos de producción.

Para equipos que necesiten un límite más estricto, usa la opción documentada flujo de trabajo del canal Capgo para automatizar previews. Describe el patrón de canal temporal y ayuda a mantener un trabajo de limpieza alejado de los canales predeterminados compartidos.

La documentación de código abierto del updater también registra el límite de eliminación: las previews activas requieren un cambio de estado o un reset previo. Puedes revisar el código fuente en el repositorio del updater de Capgo Capacitor. Ese código es útil cuando la redacción del dashboard es demasiado breve para una decisión de CI.

Consejo pro: Haz que el reset sea un paso separado y registrado. Si Delete Preview falla, el log debe mostrar si la preview seguía activa o si la solicitud de eliminación tuvo otro problema.

Una vez que el estado activo desaparece, el registro de la preview está listo para su eliminación. No combines reset y delete en una sola línea de shell opaca. Dos comandos claros son más fáciles de reintentar y mucho más fáciles de auditar.

Paso 4: Elimina los bundles de preview por ID con la clave API

Elimina cada bundle de preview por su ID exacto, después de que la preview activa se haya restablecido. Aquí es donde una clave de limpieza de Capgo elimina los objetos de almacenamiento dejados por la pull request.

Comienza con la lista de bundles del Paso 2. Para cada ID coincidente, llama a la acción Delete Bundle a través de Capgo SDK o del método API público actual disponible para tu cuenta.

Inspecciona la firma del método SDK o confirma el formato de solicitud actual con el soporte de Capgo. Registra el método y el formato de respuesta en el runbook interno de tu equipo una vez que los hayas verificado. Ese runbook debe incluir la versión de API, el identificador requerido y los códigos de error que tu lógica de reintento puede manejar.

Usa un modo dry-run en tu script. Debe imprimir el canal de preview y los IDs de bundle que eliminaría, sin enviar solicitudes de eliminación. Ejecuta ese modo contra varias pull requests cerradas. Verifica que excluya los canales de producción y que no trate una lista vacía como un comodín.

Un bucle de eliminación seguro tiene tres puertas:

1. Rechaza un ID de bundle ausente o malformado.
2. Rechaza un bundle cuyo canal no coincida con la preview de la pull request.
3. Elimina solo después de que la verificación de propiedad pase.

Luego, maneja cada respuesta según su tipo. Una eliminación exitosa se puede registrar como completada. Una respuesta de no encontrado se puede tratar como ya limpia si se sabe que el recurso fue eliminado por un reintento anterior. Los errores de permisos deben fallar el trabajo y alertar al propietario. Los límites de tasa deben pausar y reintentar con un retraso limitado.

No reintentes todos los errores. Un ID inválido no se volverá válido después de tres intentos. Un error de autorización generalmente significa que el alcance de la clave es incorrecto. Reintenta solo fallas transitorias y establece un tiempo de ejecución máximo para que un trabajo de limpieza atascado no consuma tu cola de CI.

La eliminación de bundles es independiente de la eliminación de previews. Eliminar el canal de preview no demuestra automáticamente que todos los bundles hayan desaparecido. Tu trabajo debe retener un resultado para cada ID y luego hacer una solicitud de lista final si API lo soporta. Si queda algún bundle, reporta el ID y detente en lugar de afirmar éxito en silencio.

Mantén los logs de eliminación libres de secretos. Está bien registrar el número de pull request, el nombre del preview, el ID del bundle, el resultado de la solicitud y la marca de tiempo. Nunca registres la clave de API, un encabezado de autorización o un objeto de solicitud completo que podría incluirlos.

Ese enfoque te da una pista de auditoría útil sin convertir el log en otro lugar donde las credenciales pueden filtrarse. También facilita reanudar una limpieza fallida, ya que la siguiente ejecución puede omitir los registros ya confirmados como ausentes.

Paso 5: Automatiza la limpieza al cerrar un pull request

Ejecuta el trabajo de limpieza desde el evento de cierre de pull request, pero añade comprobaciones que impidan que un build tardío elimine una nueva preview.

Tu workflow debe recibir el repositorio y el número de pull request desde el payload del evento. Reconstruye el nombre del canal de preview a partir de esos valores. No aceptes un nombre de canal proporcionado por un comentario de pull request o una variable de rama no confiable.

Una secuencia de trabajos útil se ve así:

1. Carga la clave de limpieza restringida desde secretos cifrados.
2. Confirma que el evento es un pull request cerrado.
3. Comprueba que la preview pertenece al repositorio y la app esperados.
4. Espera a que termine cualquier despliegue de preview activo.
5. Cambia de la preview o llama aresetPreview.
6. Lista los IDs de bundle para esa preview.
7. Elimina cada bundle verificado.
8. Elimina el registro de la preview.
9. Escribe un resultado breve en el resumen del workflow.

El orden importa. Si eliminas primero, la regla de preview activa puede bloquear la solicitud. Si omites la llamada de lista, puede que no sepas qué IDs de bundle siguen existiendo. Si eliminas por un nombre adivinado, corres el riesgo de tocar el recurso equivocado.

Usa una regla de concurrencia basada en el número de pull request. Cuando un evento de cierre y un evento de rebuild llegan casi al mismo tiempo, el trabajo de limpieza antiguo no debe competir con el nuevo despliegue. Cancela una ejecución de limpieza obsoleta o haz que el trabajo espere hasta que se libere el bloqueo del despliegue.

El flujo de trabajo de un solo comando de Capgo CLI puede reducir la cantidad de llamadas de shell personalizadas en torno al build y el release. Para los nombres de comandos y las operaciones admitidas, consulta la documentación del comando Capgo CLI. Usa CLI cuando te dé un comando verificado. Usa SDK o el API público cuando las acciones de limpieza necesiten una solicitud directa.

No pongas la limpieza en un flujo de trabajo que se ejecute con cada push. Un trabajo de push puede eliminar un preview que aún se está probando. El evento de cierre es el disparador correcto para la limpieza normal. Añade un dispatch manual del flujo de trabajo para recuperarte cuando falle un trabajo.

Configura también un respaldo de retención. Si se pierde un evento de cierre, un trabajo programado puede encontrar previews más antiguos que la ventana de prueba permitida por tu equipo. Ese trabajo necesita salvaguardas más estrictas que el hook de cierre normal. Debe seleccionar solo previews con un propietario claro y una marca de tiempo expirada.

Para GitHub Actions, mantén los permisos restringidos y pasa solo los valores necesarios para el paso de limpieza. La documentación actual de integración de Capgo con GitHub Actions explica dónde se almacena el token y cómo el workflow se conecta con Capgo.

A estas alturas, deberías tener un camino automatizado que reacciona al cierre, espera a los jobs en competencia, restablece el estado activo, lista los IDs y elimina solo los bundles coincidentes. Eso es lo suficientemente rápido para el desarrollo diario sin convertir la limpieza en una escoba a ciegas.

Paso 6: Verifica la limpieza y protege los rollouts frente a borrados accidentales

La verificación cierra el bucle de limpieza de previews de pull requests en Capgo. Una respuesta de eliminación por sí sola no es suficiente para un proceso de release seguro.

Después de que el job de limpieza se ejecute, vuelve a revisar el canal de preview. Confirma que ya no aparece como un preview activo. Luego, revisa la lista de bundles para la misma app y filtra. El resultado esperado es que los IDs de bundles objetivo hayan desaparecido, mientras que los bundles de producción permanezcan.

Guarda estos valores en el resumen del job:

• Repositorio y número de pull request.
• Nombre del canal de preview.
• Commit SHA used for ownership checks.
• IDs de bundles encontrados.
• IDs de bundles eliminados.
• Cualquier ID que haya devuelto un error.

Usa un estado claro. “Cleaned” significa que todos los targets verificados se eliminaron. “Already clean” significa que el recurso ya no existía. “Needs review” significa que falló una o más comprobaciones. No marques una eliminación parcial como exitosa.

Añade un guard de producción en code. Rechaza nombres de canal como tu canal default o release. También rechaza un bundle si su metadata no coincide con la app de preview. El guard debe fallar de forma segura (fail closed). Cuando el script no pueda identificar el target con certeza, debe detenerse.

Mantén el rollback separado del cleanup. Un rollback cambia qué bundle reciben los dispositivos. El cleanup elimina un recurso de preview antiguo. Si un test encuentra un bug tras cerrar el pull request, podrías necesitar el bundle para investigar. Si tu equipo suele hacer debug después del merge, define una ventana de retención corta en lugar de borrar en el momento en que llega el evento.

Vigila estos tres patrones comunes de error:

• Error de preview activa: restablece o cambia antes de reintentar Delete Preview.
• Falta el bundle ID: vuelve a ejecutar la acción de listado en lugar de adivinar.
• Error de permisos: revisa el scope de la key y emite una nueva si hace falta.

Rota la key de cleanup según el calendario que marque tu política de seguridad, y rótala de inmediato si aparece en un log o commit. Prueba la nueva key antes de revocar la anterior, a menos que la exposición exija revocarla de inmediato.

La falta de documentación sobre la limpieza merece una nota en tu revisión de seguridad. Toma como fuente para tu implementación la guía de SDK y la guía verificada de Capgo, y mantén tu propio contrato de solicitud bajo control de versiones.

Conclusión clave: Verifica la lista de previews y bundles tras la eliminación, bloquea los objetivos de producción en code y reporta la limpieza parcial como un fallo.

Un comando solo es útil cuando las protecciones están claras. Rastrea el preview. Adopta un nombre de canal predecible. Revierte los cambios de release por separado. Luego deja que el trabajo de limpieza haga su pequeña tarea sin tocar el tráfico en vivo.

FAQ

¿Puedo eliminar una preview activa de un pull request de Capgo?

No. Primero hay que salir del preview activo, o debes llamar aresetPreview. Una vez que se borre el estado activo, ejecuta Delete Preview. Esta regla es el detalle principal a recordar al configurar una clave API para la limpieza de previews de pull request de Capgo en CI.

¿Necesito bundle IDs para limpiar una preview de Capgo?

Sí. La acción Delete Bundle de Capgo requiere los IDs de los bundles, así que lista los bundles disponibles antes de eliminarlos. Asocia cada ID con el canal de preview y el commit antes de enviar una solicitud de eliminación. Nunca construyas un ID a partir del nombre de una rama ni asumas que eliminar el preview también elimina todos los bundles.

¿Qué tipo de clave de API debe usar el CI para limpiar previews?

Usa una clave de App Preview restringida para la limpieza de previews, almacenada en el almacén de secretos cifrados de tu proveedor de CI. Limita la clave a la app o al alcance que necesite. Mantenla separada de la clave usada para publicar actualizaciones de producción. Esto hace que el trabajo de limpieza de Capgo sea más fácil de revisar y más seguro de rotar.

¿Puedo automatizar la limpieza cuando se cierra un pull request?

Sí. Dispara la limpieza desde el evento de pull request cerrada, luego espera a los trabajos de despliegue activos antes de restablecer el preview. Lista los bundle IDs, elimina las coincidencias verificadas y confirma el resultado. Añade controles de concurrencia para que un build tardío no entre en conflicto con el trabajo de limpieza.

¿Por qué falla mi solicitud de limpieza de Capgo?

Las causas habituales son un preview activo, un bundle ID faltante o una clave sin el alcance necesario. Restablece el preview primero, repite la llamada de lista e inspecciona los permisos de la clave. Como los detalles de la solicitud pueden variar según la versión de API o SDK, confirma el método y los parámetros actuales antes de modificar el script.

Conclusión

Usa Capgo con una clave de preview dedicada y un orden de limpieza estricto: restablece el preview activo, lista sus bundle IDs, elimina los bundles verificados y luego elimina el preview. Comienza con una dry run contra una pull request cerrada, confirma la forma de la solicitud en el SDK actual y añade la guarda del canal de producción antes de activar la limpieza automática.