Cómo cargar el catálogo de Backstage de forma automática con repos en GitHub

Según voy avanzando en la serie de Platform Engineering, que estoy compartiendo contigo en mi canal de YouTube, te voy descubriendo nuevas necesidades que deberías de ir cubriendo si quieres proporcionar a tus desarrolladores un developer portal que les haga más felices ✨.
En el segundo capítulo de la serie te conté cómo configurar un entorno de desarrollo de Backstage y en el tercero configuro cómo cargar el catálogo de este developer portal, con entidades que hayas definido y que estén alojadas en tus repositorios de GitHub.

Si eres más de películas puedes echar un vistazo a este vídeo de la serie donde te muestro el resultado de lo que puedes leer aquí:

Si eres más de libros, sigue leyendo 👇🏻

Como generar las entidades

Antes de configurar todo lo que te voy a contar aquí, lo ideal es que antes tuvieras algunas entidades ya definidas en tus repos. Para ello puedes seguir este artículo donde se explican los diferentes tipos de entidades que idealmente podrías tener como parte de tu catálogo. Por ejemplo, podrías tener definido los dominios, sistemas dentro de estos y de qué se componentes se componen.

Una vez las tengas, ahora lo que te falta es saber cómo descubrirlas.

Instalar el plugin para GitHub Discovery

Si bien es cierto que hasta hace poco la documentación no estaba del todo actualizada, hace pocos días aprobaron la PR en la que sugerí los cambios necesarios en la documentación oficial, para poder importar el plugin que nos da esta funcionalidad 🎉 Por lo tanto, lo primero que tienes que hacer en tu instancia de backstage es instalar el mismo:

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github

Una vez lo tengas, lo siguiente que necesitas es importarlo en la ruta packages/backend/src/index.ts de tu instancia de Backstage:

// github discovery
backend.add(import('@backstage/plugin-catalog-backend-module-github/alpha'));

Crear un Personal Access Token

Para finalizar con lo que es propiamente la configuración, y que tu instancia de Backstage pueda monitorizar tu organización o tu cuenta personal, en busca de repos que potencialmente puedan tener entidades de Backstage, necesitas tener configurada la sección llamada integrations con, en este ejemplo, un Personal Access Token, que nos permita acceder tanto a la organización como a la cuenta personal, a modo de demo 😙. En mi caso, para evitar que esta información se suba accidentalmente a mi repo de GitHub la he almacenado en el archivo app-config.local.yaml:

integrations:
  github:
    - host: github.com
      # This is a Personal Access Token or PAT from GitHub. You can find out how to generate this token, and more information
      # about setting up the GitHub integration here: https://backstage.io/docs/integrations/github/locations#configuration
      token: github_pat_XXXX

Configurar el catálogo

Y ya por último necesitas añadir la configuración en la sección catalog, del archivo app-config.yaml, para que sepa en qué organización y bajo qué criterios debe buscar las entidades:

catalog:
  orphanStrategy: delete
  providers:
    github:
      returngisOrg:        
        organization: returngis
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: main
        schedule:
          frequency: { minutes: 60 }
          timeout: { minutes: 3 }

Y también puedes hacer lo mismo para una cuenta personal:

      personalAccount:
        organization: 0GiS0
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: main
          allowForks: false
          topic:
            include:
              - "backstage-include"            
        schedule:
          frequency: { minutes: 60 }     
          timeout: { minutes: 3 }

Independientemente de la configuración que necesites, ya sea para una organización o una cuenta personal, es importante que tengas en mente que la API de GitHub, como casi todas, tienen unos límites y dependiendo del tipo de cuenta serán unos u otros como puedes ver en la documentación (5.000 peticiones/hora para las cuentas personales y 15.000 peticiones/hora para las organizaciones). Es por ello que debes controlar la frecuencia con la cual refrescas contenido, con el fin de evitar que alcances el límite y comiences a recibir errores del tipo 429 (Too many requests).

El ejemplo completo lo tienes en este repo de GitHub.

¡Saludos 👋🏻!