GitHub

Verificaciones automáticasSincronización de activosSincronización de accesos

Plataforma de desarrollo y repositorios de código. Evidencia el control de acceso al código fuente y las prácticas de desarrollo seguro.

• Categoría: Herramientas de desarrollo (Dev Tools en el catálogo)
• Verificaciones: 5 (aportan evidencia a tus marcos)
• Sincroniza como activos: repositorios
• Sincroniza accesos: sí — quién tiene acceso y con qué rol
• Documentación oficial: GitHub

Qué evidencia aporta

Cada ejecución de la conexión corre estas 5 verificaciones y deja el resultado como evidencia en tus auditorías, asociado al control que aparece en la última columna.

Verificación	Severidad si falla	Aporta al control
2FA obligatorio en la organización	Alta	A.8.5 Autenticación segura
Branch protection en ramas default	Alta	A.8.28 Codificación segura
Visibilidad de repositorios	Media	A.8.3 Restricción de acceso a la información
Cantidad de owners de la organización	Media	A.8.2 Derechos de acceso privilegiados
Separación de ambientes con environments	Media	A.8.31 Separación de los entornos de desarrollo, prueba y producción

Los controles corresponden al Anexo A de la norma ISO/IEC 27001:2022. Si trabajas con otro marco, los cruces entre marcos trasladan el resultado a los requisitos equivalentes.

Qué te va a pedir la plataforma

Al crear la conexión completarás estos campos. Las credenciales se guardan cifradas y no vuelven a mostrarse.

Campo	Tipo	¿Obligatorio?
Fine-grained personal access token	Secreto	Sí
Organización (slug, ej: preceptix)	Dato de conexión	Sí

Requisitos y permisos mínimos

Tipo de token: fine-grained personal access token (NO el token clásico), de solo lectura, con Resource owner = la organización que se va a auditar.

Ámbito: la cuenta debe ser una ORGANIZACIÓN de GitHub. Una cuenta personal no sirve: los endpoints de organización responden 404 y los controles que verifica esta integración (2FA obligatorio, miembros, roles) solo existen a nivel de organización.

Permisos mínimos:

• Repository access: All repositories
• Organization permissions: Members (read) · Administration (read)
• Repository permissions: Metadata (read) · Administration (read)

Qué ocurre si falta alguno:

• Sin Members (read): no se sincronizan cuentas ni accesos, y el check de owners reporta fail explícito (una organización siempre tiene al menos un owner, así que una lista vacía significa acceso insuficiente).
• Sin Administration de organización: el check de 2FA no puede verificar y reporta fail.
• Sin Administration de repositorio: no se puede leer la protección de ramas y los repositorios aparecen como desprotegidos.

La integración solo lee: nunca escribe en GitHub. Requiere además la variable de conexión ‘org’ con el slug de la organización.

Configuración paso a paso

Estos pasos se hacen en GitHub. Cuando termines, vuelve a Preceptix y crea la conexión con los datos obtenidos (ver Conecta tu primera integración).

1. Requisito previo

   Confirma que tus repositorios estén en una ORGANIZACIÓN, no en tu cuenta personal. Si están en una cuenta personal, crea una organización (el plan Free sirve) y transfiere los repositorios antes de continuar.

2. Abre el generador de tokens

   Los tokens se crean en TU CUENTA PERSONAL, no en los ajustes de la organización (ahí solo se aprueban): Avatar (arriba a la derecha) → Settings → al final del menú lateral izquierdo: Developer settings → Personal access tokens → Fine-grained tokens → botón ‘Generate new token’. Atajo: https://github.com/settings/personal-access-tokens/new

3. Datos básicos del token

   • Token name: algo identificable, p. ej. ‘Preceptix (solo lectura)’.
   • Resource owner: selecciona LA ORGANIZACIÓN, no tu usuario. Este es el error más frecuente: un token cuyo owner es el usuario no puede leer la organización y todo falla con HTTP 404.
   • Expiration: define la vigencia según tu política y anótala; al vencer habrá que rotar el token en esta misma pantalla.

4. Repository access

   Marca ‘All repositories’. No uses ‘Public repositories’: no permite otorgar permisos de repositorio ni leer repositorios privados.

5. Permissions → Organization permissions → ‘Add permissions’

   • Members → Read-only (miembros, roles y colaboradores externos)
   • Administration → Read-only (configuración de la organización, incluye si el 2FA es obligatorio)

6. Permissions → Repository permissions → ‘Add permissions’

   • Metadata → Read-only (obligatorio; normalmente se marca solo)
   • Administration → Read-only (protección de ramas)

   ATENCIÓN: existen dos permisos llamados ‘Administration’, uno en cada sección. Se necesitan LOS DOS: el de organización para el 2FA y el de repositorio para branch protection.

7. Generar y copiar

   Pulsa ‘Generate token’ y copia el valor: GitHub lo muestra una sola vez.

8. Aprobación (si aplica)

   Si la organización exige aprobar tokens, quedará pendiente. Apruébalo en: Organización → Settings → Third-party Access → Personal access tokens → Pending requests.

9. Completa esta pantalla

   • Nombre de la conexión: libre, p. ej. ‘GitHub — Preceptix’.
   • Dominio: el dominio de Preceptix donde aterrizarán los activos, controles y evidencia.
   • Token: el valor copiado en el paso 6.
   • Organización: el slug tal como aparece en la URL github.com/<slug>.

   Pulsa ‘Probar conexión’ antes de guardar: valida el token contra la API real sin guardar nada.

---

¿Falla la conexión o una verificación queda en rojo? Revisa Estado y cobertura.