Norma de uso del repositorio de código corporativo

Ámbito de aplicación de la norma

La Junta de Andalucía tiene como objetivo estratégico la estandarización de las herramientas y normas corporativas para la homogeneización del ciclo de vida del desarrollo de un producto software, por lo que el uso del repositorio de código corporativo se extiende a toda la ADA.

Por tanto:

• Todo sistema de información nuevo que sea desarrollado estará ubicado en el repositorio de código corporativo.
• Cualquier otro sistema de información de la ADA, teniendo en cuenta sus posibles restricciones tecnológicas o presupuestarias.
• Todo sistema de información que:
  • se encuentre en el Proceso de Transición a DevSecOps, debe utilizar el repositorio de código corporativo.
  • se encuentre operativo o en desarrollo para ser desplegado en las infraestructuras de despliegue de la ADA, utilizando el modelo DevSecOps impulsado por el Servicio de Gobierno TI y Calidad, debe utilizar el repositorio de código corporativo.       
     

Puedes conocer en esta sección cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma.

Uso del repositorio de código

DIR_01 Uso del repositorio de código

OBLIGATORIO El código de los Sistemas de Información será custodiado en el repositorio de código corporativo definido no existiendo otra opción.

Para los Sistemas de Información ya existentes y que utilizan otros repositorios corporativos, existen varias opciones:

• Empezar a trabajar desde una determinada versión con el repositorio de código corporativo, dejando el anterior como referencia.
• Realizar una migración del repositorio actual el repositorio de código corporativo. Para ello, la Oficina de Impulso DevSecOps ofrecerá soporte en las tareas de migración.

Se DEBE versionar todo el código fuente del proyecto, incluyendo:

• Archivos fuentes java, javascript,  python, etc.
• Archivos HTML, CSS, plantillas, etc
• Test unitarios
• Pruebas automatizadas
• Ficheros de manifiesto
• Scripts SQL
• etc

NO DEBE incluirse en el repositorio:

• binarios (a excepción de imágenes y otros recursos similares para montar el proyecto).
• los artefactos intermedios de una compilación ni los generados finalmente.
• ficheros o directorios de configuración del IDE utilizando durante el desarrollo.

Se utilizará un fichero ".gitignore" para asegurar que no se incluye en el repositorio contenido no deseado. A continuación, se muestra un ejemplo de cómo podría ser dicho fichero para tecnología JAVA:

• # Ficheros compilados
  • *.class
• # Ficheros de log
  • *.log
• # Ficheros temporales
  • *.tmp
  • *.swp
• # Relacionados con Eclipse
  • .project
  • .classpath
  • .settings/
• # Relacionados con IntelliJ
  • *.iml
  • *.ipr
  • *.iws
• # Directorio target originado por una tarea de construcción
  • target/

DIR_02 Alineamiento con GitOps

OBLIGATORIO La gestión de configuraciones de infraestructura y aplicaciones DEBE alinearse con la metodología GitOps, utilizando Git como fuente única de verdad para garantizar control, trazabilidad y automatización en los despliegues.

GitOps es una metodología para la gestión de configuraciones de infraestructura y aplicaciones mediante el uso de Git como repositorio central de verdad. La idea es tratar las configuraciones de infraestructura y aplicaciones como código y utilizar herramientas de Git para controlar su versión y despliegue. Esto permite un mayor control y visibilidad sobre los cambios en la infraestructura y facilita la colaboración y la automatización a los equipos de operaciones. Se fomentará la adopción de esta metodología en el repositorio.

Organización del repositorio de código

DIR_03 Organización y estructura tipo un Sistema de Información

OBLIGATORIO La organización y estructura del repositorio DEBE seguir una jerarquía estandarizada para garantizar coherencia, escalabilidad y eficiencia en la gestión del código. Los niveles de la estructura se ajustarán a los criterios establecidos. Cualquier desviación requiere validación por la Oficina de Impulso DevSecOps.

La implementación de una estructura de repositorio persigue la consecución de múltiples objetivos estratégicos, en aras de optimizar el ciclo de vida del desarrollo de software. Los principales objetivos son los siguientes:

• Proporcionar una estructura organizativa coherente que simplifique la gestión de proyectos, promoviendo la eficiencia en el desarrollo al reducir la complejidad de navegación y organización de los repositorios.
• Proporcionar una estructura flexible y escalable que se adapte a la diversidad de proyectos y sistemas, permitiendo la gestión eficaz de múltiples niveles de complejidad sin sacrificar la claridad organizativa.
• Establecer una estructura que sirva como base sólida para los nuevos proyectos que ingresan al entorno Pre-Cloud, asegurando una transición suave y coherente hacia esta fase del desarrollo.
• Asegurar la coherencia y compatibilidad en todos los sistemas, facilitando la interoperabilidad con otras herramientas y garantizando una experiencia uniforme para los equipos de desarrollo.

Se ofrecen dos elementos para jerarquizar los contenidos del repositorio:

• grupos: Actuarán como contenedores de usuarios y proyectos. Facilitan la organización y gestión de permisos dentro del repositorio.
• proyecto: Espacio que contendrá el código para un componente concreto del Sistema de Información.

Estructura

La estructura organizativa en el repositorio se dividirá, principalmente, en N niveles jerárquicos. Cada nivel tiene un propósito específico y sigue una convención de nombres estandarizada (consultar documento de nomenclatura) para facilitar la identificación y gestión de los activos.

Esta estructura podrá adoptarse sin mayores problemas para la mayoría de los Sistemas / Sistemas de Información. Si por alguna razón se necesitase tener una estructura distinta (por ejemplo, establecer una estructura jerárquica mayor), habrá que acordar con la Oficina de Impulso DevSecOps dicha estructura, para identificar potenciales problemas o inconvenientes. No obstante, se seguirán las convenciones propuestas de manera generalizada.

Primer nivel: Sistemas / Sistemas de Información / Servicio de apoyo

El primer nivel, situado en la raíz del repositorio y representado siempre por un grupo, puede ser uno de los siguientes:

• Sistema: representa una agrupación de Sistemas de Información.
• Sistema de Información: conjunto de activos que engloba elementos de software así como procesos que se implementan para ofrecer uno o más servicios de negocio.       
  Esta conceptualización implica una integración de componentes que funcionan como un único sistema ante el usuario.       
  Tiene los mismos responsables tanto de información, como de servicio y del propio sistema, y por ello es tratado como una sola entidad para las tareas de calidad y seguridad.
• Servicio de apoyo: servicios de apoyo de la ADA, que se pueden consultar en el Portal de Desarrollo de Sistemas Digitales o en la Intranet de la ADA

Niveles intermedios: Estructura lógica / Sistema de Información

En el segundo nivel, nos podemos encontrar:

Estructura Lógica: Subgrupos opcionales que podrán ser utilizados para la organización de los componentes de manera lógica y coherente.

Sistemas de Información: Si en primer nivel se ha definido un Sistema o Servicio de Apoyo, este será el caso. Pueden existir múltiples Sistemas de Información dentro de un Sistema o Servicio de Apoyo. Se usarán GRUPOS de Gitlab para definir los distintos Sistemas de Información. Una vez creado un Sistema de Información, no podrá existir ningún otro Sistema de Información por debajo de su jerarquía.

Último nivel: Componente

El último nivel, siempre corresponde a los componentes. En este contexto, se entiende como el espacio destinado a contener el código asociado a un Componente específico del Sistema de Información o del Servicio de Apoyo.

Un componente se caracteriza por ser un elemento que proporciona un servicio de software predefinido, con una interfaz claramente definida y capaz de comunicarse con otros componentes.

Cada componente es versionable y desplegable de forma independiente, lo que facilita su gestión y mantenimiento dentro del entorno del Sistema de Información o del Servicio de Apoyo.

Ejemplos

A continuación, se presenta un esquema ilustrativo del sistema de organización:

A modo de ejemplo:

DIR_04 Nomenclatura

OBLIGATORIO La nomenclatura en el repositorio DEBE seguir un estándar definido para garantizar coherencia, claridad y facilidad de gestión. Los nombres de grupos, subgrupos y componentes se ajustarán a las reglas establecidas, evitando ambigüedades y facilitando su identificación.

Directrices de nomenclatura 

En esta sección se detallarán las convenciones para asignar nombres a los grupos, subgrupos y componentes.

Tipos de grupo:

• Sistema 
• Sistema de información 
• Servicio de apoyo 

Para asegurar una nomenclatura coherente y fácil de seguir en el respositorio, se aplicarán las siguientes directrices generales:

1. Inicio del Nombre:
   • Debe comenzar con una letra. 
2. Cuerpo del Nombre:
   • Puede contener letras y números.
   • No se permite el uso de caracteres especiales a excepción de los indicados a continuación:
     • El guion ("-") se usará para separar el tipo de grupo del nombre.
     • El punto (".") no tiene una utilidad específica asignada y puede ser utilizado según sea necesario. 
3. No se permite el uso de letras mayúsculas en ningún momento, tanto en el inicio como en el cuerpo.

La nomenclatura específica que deberá tener un nombre de grupo o subgrupo será:

• ({tipo de grupo}-{nombre de grupo} donde "tipo de grupo” podrá tomar los siguientes valores:)
  • Sistema: s-nombre_del_grupo
  • Sistema de información: si-nombre_del_grupo/subgrupo
  • Servicio de apoyo: sa-nombre_del_grupo

Los subgrupos utilizados como Estructura lógica dentro de un Sistema, Sistema de información o un Servicio de apoyo deben seguir las directrices generales. (No tienen "tipo de grupo").

En el caso del nombre de los componentes, se aplicarán las directrices generales.

Ejemplo:      
    
 

Gestión de permisos de usuarios y grupos

DIR_05 Gestión de permisos en el repositorio de código

OBLIGATORIO La gestión de permisos en el repositorio de código será autogestionado, otorgando a los equipos mayor autonomía y responsabilidad en la administración de accesos, bajo la supervisión del Director de Proyecto (DP).

Para la gestión de permisos en el repositorio de código se ha optado por la implementación de un modelo de autogestión. Este cambio está pensado para otorgar mayor autonomía y flexibilidad a los distintos equipos de desarrollo.

Los principales objetivos que persigue este cambio son:

• Autonomía: Permitir a los equipos gestionar sus propios permisos, facilitando la incorporación o bajas de recursos de manera directa.
• Responsabilidad: Fomentar un sentido de responsabilidad y propiedad sobre los grupos/repositorios, mejorando la colaboración y la productividad.
• Eficiencia: Reducir la carga administrativa centralizada, permitiendo una gestión de permisos más rápida, adaptada a las necesidades específicas de cada equipo, minimizando las solicitudes de soporte.

En este escenario, los Directores de Proyectos funcionarios (en adelante DP) serán responsables de asignar roles y permisos a los miembros del equipo según sea necesario. Podrán delegar esta asignación en otros roles, bajo su responsabilidad.

En este modelo, el DP solo necesitará crear una primera petición para la creación de un grupos para cada sistema de información y/o servicio de apoyo del que sea responsable, que se situará en la raíz del repositorio.

DIR_06 Creación del grupo

OBLIGATORIO Todo Sistema de Información o Servicio de Apoyo debe contar con un grupo raíz en GitLab, gestionado por su Director de Proyecto (DP), quien será responsable de su administración y organización, siguiendo la nomenclatura y el proceso de solicitud establecido. 

En primer lugar, se denomina “grupo raíz", al grupo que representa a un Sistema, Sistema de Información o Servicio de Apoyo, gestionado por un propietario (normalmente el DP) a partir del cual, se desarrollará toda la estructura lógica del repositorio.

Solo los DP podrán realizar este tipo de peticiones, aunque podrán delegar la administración a quien consideren oportuno, teniendo en cuenta que esa persona o personas deben tener cierto conocimiento de los componentes que integran el sistema y los implicados en el mismo, además de conocimiento básico de cómo funcionan los repositorios de tipo Git y sistemas de gestión de productos tipo GitLab.

A los subgrupos del grupo raíz (y siguientes), por simplicidad, lo referenciaremos a lo largo del documento como “grupos”.

Estas peticiones deben realizarse vía NAOS, por el Director del Proyecto, a la Oficina de Impulso DevSecOps.

La categorización que debe emplearse es la siguiente:

• Operación: Realizar petición
• Servicio: DSO - Impulso DevSecOps
• Componente: Soporte de las herramientas de apoyo DevSecOps
• Elemento: (Sin determinar)

En el asunto de la petición, se indicará:

  [GITLAB] Creación grupo raíz para SI-'Nombre del sistema'

En la descripción, se detallará la solicitud. La nomenclatura del grupo raíz para el Sistema, Sistema de Información o el Servicio de Apoyo correspondiente, deberán seguir las pautas indicadas en esta norma.

Como la petición tiene que venir del DP del Sistema de Información o Servicio de Apoyo, se le asignará el rol de Owner al SOLICITANTE de la petición. A partir de ese momento es responsabilidad total y absoluta de dicha persona para gestionar dicho grupo raíz y todo su contenido, así como sus accesos.

Importante: Si tienes cualquier duda durante el proceso, no dudes en contactar con la Oficina de Impulso de DevSecOps para que te acompañe durante todo el proceso.

Estrategia de ramificación y política de versionado

DIR_07 Uso de la estrategia de ramificación

OBLIGATORIO El desarrollo y despliegue del software debe seguir la estrategia de ramificación de la ADA, garantizando control, trazabilidad y estabilidad a través del uso de ramas y solicitudes de fusión (Merge Requests).

Esta norma es obligatoria para todo sistema de información que:

• se encuentre en el Proceso de Transición a DevSecOps, debe utilizar el repositorio de código corporativo.
• se encuentre operativo o en desarrollo para ser desplegado en las infraestructuras de despliegue de la ADA, utilizando el modelo DevSecOps impulsado por el Servicio de Gobierno TI y Calidad, debe utilizar el repositorio de código corporativo.
• Utiliza la Plataforma CI/CD dentro de las prácticas DevSecOps.

Para el resto de los Sistemas de Información se recomienda su uso.

Se ha definido una estrategia de ramificación basada en Gitlab Flow, en el que el uso de ramas representa el estado del código en cada entorno de ejecución y el uso de solicitudes de fusión (Merge Requests), para orquestar y garantizar los despliegues.

El detalle de la estrategia a seguir se describe en Estrategia de ramificación.

 DIR_08 Política de Versionado Software

OBLIGATORIO Todo software debe seguir una política de versionado estándar basada en Versionado Semántico (SEMVER) para garantizar coherencia, trazabilidad y compatibilidad en su evolución.

Esta norma es obligatoria para todo sistema de información que:

• se encuentre en el Proceso de Transición a DevSecOps, debe utilizar el repositorio de código corporativo.
• se encuentre operativo o en desarrollo para ser desplegado en las infraestructuras de despliegue de la ADA, utilizando el modelo DevSecOps impulsado por el Servicio de Gobierno TI y Calidad, debe utilizar el repositorio de código corporativo.
• Utiliza la Plataforma CI/CD dentro de las prácticas DevSecOps.

Para el resto de los Sistemas de Información se recomienda su uso.

De cara a garantizar que todos los productos o componentes software sigan una política de versionado estándar, se deben aplicar las pautas marcadas por SEMVER (Versionado Semántico), que se resumen a continuación:

1. El software que use Versionado Semántico DEBE declarar un elemento de infraestructura, configuración o despliegue. Este, puede ser declarado en el código mismo o existir en documentación estricta que, de cualquier manera, debería ser precisa y completa.
2. Un número normal de versión DEBE tomar la forma X.Y.Z donde X, Y, y Z son enteros no negativos. X es la versión “major”, Y es la versión “minor”, y Z es la versión “patch”. Cada elemento DEBE incrementarse numéricamente en incrementos de 1. Por ejemplo: 1.9.0 -> 1.10.0 -> 1.11.0.
3. Una vez que un paquete versionado ha sido liberado (release), los contenidos de esa versión NO DEBEN ser modificados. Cualquier modificación DEBE ser liberada como una nueva versión.
4. La versión major en cero (0.y.z) es para desarrollo inicial. Cualquier cosa puede cambiar en cualquier momento. El elemento no debe ser considerada estable.
5. La versión 1.0.0 define el elemento. La forma en que el número de versión es incrementado después de este release depende de este elemento y de cómo cambia.
6. La versión patch Z (x.y.Z | x > 0) DEBE incrementarse cuando se introducen solo arreglos compatibles con la versión anterior. Un arreglo de bug se define como un cambio interno que corrige un comportamiento erróneo.
7. La versión minor Y (x.Y.z | x > 0) DEBE ser incrementada si se introduce nueva funcionalidad compatible con la versión anterior. Se DEBE incrementar si cualquier funcionalidad del elemento es marcada como deprecada. PUEDE ser incrementada si se agrega funcionalidad o arreglos considerables al código privado. Puede incluir cambios de nivel patch. La versión patch DEBE ser reseteada a 0 cuando la versión minor es incrementada.
8. La versión major X (X.y.z | X > 0) DEBE ser incrementada si cualquier cambio no compatible con la versión anterior es introducido en el elemento. PUEDE incluir cambios de nivel minor y/o patch. Las versiones patch y minor DEBEN ser reseteadas a 0 cuando se incrementa la versión major.

De forma resumida:

X: Aumentará cuando se producen cambios que rompan la compatibilidad de alguna manera con la versión anterior. (major).

Y: Aumentará con cada funcionalidad añadida compatible con la versión anterior. (minor).

Z: Aumentará con correcciones compatibles con la versión anterior. (patch).

Para más información sobre consultar: Versionado Semántico 2.0.0-rc.2 (https://semver.org/lang/es/).