Importar y sincronizar complementos desde GitHub

Puedes importar complementos desde GitHub a tu Espacio de trabajo y mantenerlos actualizados a medida que cambia el repositorio. Un marketplace es un archivo JSON que contiene la lista de complementos que se van a importar.

Antes de comenzar

Debes ser administrador del Espacio de trabajo. Usa una cuenta de GitHub con acceso de lectura al repositorio del marketplace y a todos los repositorios a los que este haga referencia. Se admiten repositorios de GitHub tanto públicos como privados. Antes de iniciar la importación, obtén las aprobaciones de acceso que exija tu organización de GitHub.

Revisa el repositorio antes de importarlo. La siguiente configuración predeterminada afecta lo que pueden usar los miembros:

• Los complementos nuevos tienen el estado Disponible para que los miembros puedan instalarlos. Si un complemento requiere autenticación, los miembros se autentican al instalarlo.
• La importación procesa todas las entradas válidas. Los marketplaces nuevos se sincronizan automáticamente todos los días e incorporan los complementos nuevos del repositorio.

Esta guía explica cómo importar complementos a un Espacio de trabajo. Para clientes locales, consulta Configurar marketplaces de complementos y opciones predeterminadas para conocer las opciones de config.toml administradas desde la nube o configuradas en el sistema. Para un proyecto específico, consulta Habilitar o deshabilitar un complemento para un repositorio.

Configurar la sincronización de un marketplace

1. Abre Administración > Complementos y selecciona Agregar > Importar marketplace.
2. En Origen, ingresa la URL del repositorio, por ejemplo, https://github.com/example/team-plugins. Usa solo la URL del repositorio, sin incluir la ruta a una rama o carpeta.
3. Si el marketplace está en un subdirectorio, ingresa ese directorio en Ruta. Por ejemplo, usa team-tools para team-tools/.agents/plugins/marketplace.json. Deja Ruta en blanco para usar la raíz del repositorio. No ingreses el nombre del archivo de manifiesto.
4. Si quieres, ingresa un valor en Rama, etiqueta o commit. Deja el campo en blanco para usar la rama predeterminada del repositorio. Una rama te permite recibir actualizaciones posteriores. Si especificas un commit fijo, conservas la versión que seleccionaste.
5. Selecciona Importar marketplace y autoriza el acceso a GitHub cuando se te solicite. La importación inicial puede tardar hasta una hora si el marketplace es especialmente grande. Las sincronizaciones diarias posteriores suelen tardar unos minutos.
6. Revisa Resultados de la importación y luego abre cada complemento importado para configurar su política de instalación y las apps que requiera.

Formatos compatibles

El directorio seleccionado debe contener uno de estos archivos:

Las entradas de un marketplace pueden hacer referencia a complementos nativos con .codex-plugin/plugin.json, complementos compatibles con Claude, paquetes de Agent Plugins 1.0 o paquetes de habilidades compatibles.

En un marketplace de Codex, usa rutas locales para los complementos que estén en el mismo repositorio:

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

La ruta es relativa a la raíz seleccionada para el marketplace, no a .agents/plugins/.

Un marketplace compatible con Claude puede indicar la ruta de cada complemento local mediante una cadena de texto:

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Las entradas de un marketplace de Codex también admiten source: "url" para un complemento ubicado en la raíz de un repositorio de GitHub y source: "git-subdir" para un complemento ubicado en un subdirectorio de un repositorio de GitHub. Por ejemplo:

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Para los orígenes de Git, puedes seleccionar una referencia con ref o indicar el identificador completo de 40 caracteres de un commit con sha. La cuenta de GitHub que autoriza el acceso debe tener acceso de lectura a todos los repositorios referenciados. Actualmente, la importación al Espacio de trabajo solo admite repositorios de GitHub.

Configurar el acceso en el Espacio de trabajo

Configura las opciones de instalación y autenticación de cada complemento en tu Espacio de trabajo. La importación y la sincronización no aplican estas opciones desde el repositorio. Entre ellas se encuentran AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL y ON_USE. La configuración existente del Espacio de trabajo se conserva cuando sincronizas una actualización o pasas a administrar un complemento desde GitHub.

En Política de instalación, elige Disponible o Instalado para cada rol al que se aplique la política. Habilita también las apps que necesita el complemento y verifica que los miembros tengan acceso al servicio conectado. Importar un complemento no da a los miembros acceso a las apps ni conecta sus cuentas. Consulta Controles de los complementos para elegir la configuración de acceso y de acciones.

Pasar a administrar un complemento existente desde GitHub

Agrega pluginId a la entrada del complemento existente en el marketplace:

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Abre el complemento desde Administración > Complementos y copia el ID que aparece después de /plugins/ en su URL. Coloca pluginId junto a name y source en la entrada del marketplace. El complemento existente debe estar en el mismo Espacio de trabajo y el valor de name de la entrada debe coincidir con el nombre del complemento existente.

Usa este método para pasar a administrar un complemento del Espacio de trabajo desde GitHub si aún no se administra allí. El complemento conserva su ID, las opciones de uso compartido y la configuración del Espacio de trabajo. Las actualizaciones futuras provendrán de GitHub, por lo que ya no podrás reemplazar el complemento subiendo un archivo comprimido. No puedes usar este método para un complemento que ya se administra desde otro origen de GitHub.

Complementos exclusivos para escritorio

Los complementos con la etiqueta Solo para escritorio no pueden ejecutarse en la versión web de ChatGPT. Los complementos importados pueden recibir esta etiqueta si declaran servidores MCP, incluidos los servidores con URL HTTPS remotas. Agregar una referencia a .app.json no basta para quitar la etiqueta.

Hacer referencia a una app existente con .app.json

Agrega .app.json en la raíz del complemento. El nombre del archivo comienza con un punto. No se admite app.json sin el punto.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Reemplaza asdk_app_example por el ID de la app existente. Los ID de app compatibles comienzan con asdk_app_, connector_ o templated_apps_. Usa el ID de la app, no un ID plugin_.... Por ejemplo, la URL de un complemento que contiene plugin_asdk_app_example representa la app asdk_app_example.

La clave team-tools da nombre a la referencia dentro de este archivo. Asigna a required el valor true cuando el complemento dependa de la app. Puedes agregar más entradas para hacer referencia a otras apps existentes.

Para un complemento nativo, asigna a apps el valor ./.app.json en .codex-plugin/plugin.json. Este es el archivo de manifiesto completo para este ejemplo:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Mantén esta estructura de archivos:

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

Este archivo hace referencia a una app existente. No crea una app ni concede acceso a nadie. Habilita la app para los roles que la necesiten y pide a los miembros que completen la autenticación que se requiera. Se siguen aplicando los permisos de la app, las acciones permitidas y las condiciones de acceso al servicio conectado.

Mantener los complementos actualizados

Los marketplaces nuevos buscan actualizaciones a diario. Abre Administración > Complementos > Marketplaces, selecciona el marketplace y elige Sincronizar ahora para solicitar una actualización sin esperar a la sincronización automática.

La sincronización puede agregar complementos nuevos del marketplace y actualizar los existentes. Revisa los cambios del repositorio antes de fusionarlos, ya que la sincronización automática también importa complementos nuevos.

Después de cada sincronización, revisa el estado y lee el informe guardado. Aunque la sincronización se complete, puede haber errores en algunos complementos. Si una actualización no es válida, el complemento existente conserva la última versión que funcionaba. Corrige el problema en GitHub y selecciona Sincronizar ahora para volver a intentarlo.

Si quitas la entrada de un complemento del marketplace, la copia del Espacio de trabajo se conserva con la etiqueta Ya no está en el origen. Si eliminas el marketplace en ChatGPT, se eliminan todos los complementos importados desde ese marketplace.

Volver a conectar GitHub o cambiar el acceso

La sincronización del marketplace usa la conexión de GitHub del administrador que lo importó.

Para restablecer la conexión, primero verifica que la cuenta de GitHub del administrador que importó el marketplace siga teniendo acceso de lectura al repositorio del marketplace y a todos los repositorios a los que este haga referencia. Luego, ese administrador debe abrir el complemento de GitHub en ChatGPT y volver a conectar su cuenta.

Para cambiar de propietario, el nuevo administrador del Espacio de trabajo debe volver a importar el marketplace desde Administración > Complementos > Agregar > Importar marketplace. Usa los mismos valores de Origen, Ruta y Rama, etiqueta o commit. Las sincronizaciones futuras usarán la conexión de GitHub del nuevo administrador.

Conserva el marketplace cuando restablezcas la conexión o cambies de propietario. Si lo eliminas, también se eliminarán los complementos importados desde él.