Integración de propiedades personalizadas con un sistema externo

Puede escribir automáticamente metadatos desde un sistema externo, como un catálogo de software o un portal para desarrolladores interno, a las propiedades personalizadas del repositorio en GitHub. Esto hace que el sistema externo sea el origen de estas propiedades y le ayuda a mantener el contexto empresarial, como la propiedad, el nivel de servicio o el estado de cumplimiento actualizados en los repositorios. Las propiedades externas se pueden usar en los mismos lugares que las propiedades personalizadas que se administran en GitHub.

Para configurar esta automatización, instalarás un GitHub App que llama a los endpoints de la API de GitHub para propiedades externas con datos del sistema externo.

• Nuestro asociado de integración Port ha desarrollado una integración para propiedades personalizadas externas. Para conocer todos los pasos necesarios para sincronizar los metadatos desde el puerto, consulte Propiedades de puerto de sincronización con GitHub propiedades personalizadas externas en la documentación del puerto. GitHub trabajará para añadir más proveedores en el futuro.
• Si su organización usa otro sistema externo, o si es representante de un sistema externo que quiere crear una integración con GitHub, deberá crear su propia GitHub App y automatización. Siga leyendo esta guía.

Prerequisites

Este proceso puede requerir varias personas diferentes. Necesitará lo siguiente:

• Alguien que configure GitHub App en su cuenta personal o en una cuenta de organización o de empresa de la que sea propietario
• Uno o varios propietarios de la organización en GitHub para instalar la aplicación en cada organización donde sea necesario y, posiblemente, registrar un nombre para mostrar para la aplicación

Fuera del ámbito de esta guía, también necesitará a alguien que pueda crear y ejecutar la automatización, con el acceso adecuado al sistema externo y al servidor donde se ejecutará la automatización.

1. Elija un nombre para mostrar.

Cada clave de propiedad personalizada externa de la organización tendrá como prefijo un nombre para mostrar. Por ejemplo: port.environment. Esto actúa como un espacio de nombres y ayuda a evitar conflictos con propiedades personalizadas administradas en GitHub u otros proveedores externos.

Cada nombre para mostrar está restringido a una sola instalación de GitHub App dentro de la organización. Para que una aplicación pueda escribir propiedades personalizadas en GitHub, debe registrar la instalación de la aplicación con un nombre visible. Se trata de un proceso único que puede realizar la propia aplicación o un administrador de la organización. Una instalación de la aplicación solo se puede registrar una vez y su nombre para mostrar no se puede cambiar más adelante.

Elija un nombre que evite conflictos y ayude a los usuarios a identificar las propiedades personalizadas del sistema externo. Si va a publicar una aplicación en nombre de un sistema de terceros, puede que quiera responder a conflictos o permitir que los usuarios elijan su propio nombre para mostrar como parte del flujo de configuración en el sistema.

El nombre para mostrar debe tener entre 1 y 15 caracteres y contener solo letras y números. Para conocer todos los requisitos, consulte el punto de conexión Registrar una instalación de aplicación para propiedades externas de la API de REST.

2. Registre un GitHub App

GitHub App es la identidad que llamará a las API para administrar propiedades personalizadas externas. También puede escuchar webhooks de eventos en GitHub.

Si va a crear una aplicación para un proceso interno, se recomienda crear la aplicación en una organización o una cuenta empresarial. A continuación, podrá instalar la aplicación en tantas organizaciones como necesite. Si representa a un sistema de terceros, es probable que publique la aplicación en GitHub Marketplace para que otras empresas puedan instalarla.

Para obtener instrucciones, consulte Registro de una aplicación de GitHub.

Selección de permisos

En Permisos de organización, habilite las propiedades personalizadas externas para el permiso repositorios para que la aplicación pueda escribir datos en la API de propiedades externas. El nivel de acceso necesario depende de lo que la aplicación debe hacer:

• Elija Acceso de administrador si la aplicación registrará su propio nombre para mostrar mediante su token de acceso de instalación. Este es un buen modelo para una aplicación de autoservicio que se instalará en muchas organizaciones.
• Elija Acceso de lectura y escritura si la aplicación solo necesita escribir propiedades personalizadas en GitHub. Un administrador de la organización tendrá que registrar el nombre visible de su instalación.

Acceso de solo lectura no es una opción para esta tarea. Una aplicación con este nivel de acceso solo podrá leer sus propias definiciones de propiedades personalizadas externas.

Si desea suscribirse a eventos de webhook, es posible que tenga que habilitar permisos adicionales.

Para obtener más información, vea Permisos necesarios para aplicaciones de GitHub.

Selección de webhooks

Puede habilitar los webhooks para suscribirse a eventos en GitHub que desencadenen la transferencia de datos desde su sistema externo.

Por ejemplo:

• Cuando se instala una aplicación en una organización (el installation evento con la created acción), esto puede desencadenar la primera sincronización desde el sistema externo a los repositorios de la organización. Este evento se envía a todos los GitHub Apps de forma predeterminada.
• Cuando se crea un nuevo repositorio en la organización (el repository evento con la created acción), el repositorio se puede rellenar automáticamente con metadatos. Este evento requiere acceso de lectura al permiso del repositorio de metadatos .

Los webhooks no son necesarios si prefiere que la automatización se ejecute simplemente según una programación.

Para obtener más información, vea Uso de webhooks con aplicaciones de GitHub.

Selección del ámbito de instalación

En ¿Dónde se puede instalar esta aplicación GitHub?, asegúrese de que la aplicación se puede instalar en todas las organizaciones en las que sea necesario.

3. Creación de la automatización

La automatización se puede ejecutar según una programación o escuchar eventos. El webhook que seleccionaste para la app determina qué eventos GitHub se reenvían a la URL del webhook. También puede que quiera responder a eventos en el sistema de terceros, como cambios en los valores de metadatos.

En la automatización, el GitHub App debe obtener un token de acceso a la instalación y usarlo para enviar datos desde el sistema externo a los puntos de conexión de la API de propiedades externas de GitHub. Consulte Autenticación como una instalación de una aplicación de GitHub.

Consulte los siguientes puntos de conexión de la API REST. Encontrará información sobre los límites de tamaño de solicitud y los códigos de error para los que debe tener en cuenta la automatización.

• Registrar una instalación de aplicaciones para propiedades personalizadas externas (la aplicación debe registrar su nombre para mostrar para poder actualizar las propiedades, a menos que se espere que un administrador de la organización lo haga).
• Obtener instalaciones registradas de aplicaciones para propiedades personalizadas externas
• Obtener todas las propiedades personalizadas externas de una GitHub App instalación en una organización
• Creación o actualización de valores de propiedad personalizados externos para repositorios de la organización
• Creación o actualización de valores de propiedad personalizados externos para una propiedad entre repositorios de la organización
• Quitar todos los valores de propiedad personalizados externos de una propiedad en todos los repositorios de la organización

4. Instalación de la aplicación

Instale el GitHub App en las organizaciones donde sea necesario, autorizando los permisos que necesite. Consulte Instalación de su propia aplicación de GitHub.

Dado que el permiso de propiedades personalizadas externas tiene ámbito de organización, la aplicación se instalará con acceso a todos los repositorios de forma predeterminada. No verá una opción para seleccionar repositorios individuales a menos que la aplicación también tenga permisos de nivel de repositorio.

Si la aplicación no registra automáticamente un nombre visible o no puede autorizar el acceso de administrador, un administrador de la organización debe registrar el nombre visible de la instalación. Puede tratarse de un propietario de la organización o de alguien con el permiso organization_external_properties_for_repos:admin detallado. Consulte Registrar una instalación de aplicación para propiedades personalizadas externas.

5. Validar la transferencia de datos

Una vez que se haya ejecutado la automatización, compruebe que las propiedades externas se están sincronizando con los repositorios de la organización. Deberías poder ver estas opciones en la configuración de las propiedades personalizadas de tu organización o de sus repositorios. Las claves de propiedad irán precedidas del nombre visible externo, y los valores se indicarán mediante un icono . Consulte Administración de propiedades personalizadas para repositorios de la organización.

Los valores de propiedades externas también se devuelven junto a las propiedades personalizadas tradicionales en el punto de conexión de la API REST Obtener todos los valores de propiedades personalizadas de un repositorio. Sin embargo, /schema los puntos de conexión de las propiedades personalizadas, como "Obtener todas las propiedades personalizadas de una organización", no devuelven propiedades externas.

Los usuarios no podrán editar estas propiedades en GitHub, pero podrán usarlas en cualquier lugar donde usen propiedades personalizadas tradicionales.

6. Mantener la integración

Mantenga la automatización en ejecución y la aplicación instalada para mantener la sincronización de datos desde el sistema externo. Si desinstala el GitHub App de una organización, se darán de baja la instalación y el nombre para mostrar, y se eliminarán todas las propiedades externas que creó la aplicación.

Preste atención al número de propiedades definidas en la organización. Cada organización puede tener hasta 100 definiciones de propiedades. Tanto las propiedades personalizadas externas como las estándar se contabilizan para este límite.