Intro

On Q4 of 2021 a functionality has been added that allows us to have versioned platform elements, such as ontologies, dashboards, gadgets, apis..., in a Git repository, so that we can have a control of changes on these elements and restore a previous version at any time.

In addition, we can generate tagged versions of the elements (tags in Git), so that in case of migration or if we want to restore a particular version of the elements, we can do it without problems.

Requisitos para habilitar el versionado

Para poder habilitar el versionado de elementos en una instalación de plataforma necesitaremos:

• Repositorio Git (GitHub o GitLab) con un token de API con permisos de escritura

• Role administrator: solo los administradores pueden configurar esta funcionalidad

Configuración del repositorio Git

En primer lugar, tendremos que configurar el repositorio Git que va a utilizar la plataforma para ir versionando los elementos. La plataforma trabajará siempre en la misma rama de Git establecida en la configuración.

Para configurarlo, iremos al menú > Version Control > Configuration

Aquí rellenaremos todos los campos necesarios y marcaremos la opción de crear repositorio si así lo deseamos:

En caso de tener ya un repositorio creado, desmarcar la opción.

Una vez configurado, podremos modificar la configuración en cualquier momento, incluso deshabilitar el versionado de recursos temporalmente (botón arriba a la izquierda). También podremos borrar directamente la configuración.

Además, en el momento de configurarlo, se nos generará un SNAPSHOT de los recursos actuales en el repositorio:

Formato de serialización de los elementos

Para serializar las entidades o elementos del sistema de versionado, hemos elegido el formato Yaml, ya que para elementos como los Dashboards o Gadgets, nos permite mostrar el contenido HTML de manera legible.

Además, si queremos editar el fichero para luego restaurarlo, será mucho más sencillo.

Mensaje de commit en edición y creación

Cuando se habilita el sistema de versionado, nos empezaran a aparecer pop-ups con un cuadro de texto para introducir un mensaje de commit a la hora de crear o actualizar elementos versionables.

Por ejemplo, al editar una ontología:

Si dejamos el commit vacío, se pondrá un mensaje de commit genérico, indicando el usuario que ha editado o creado el elemento.

Histórico de cambios, restauración y edición de un elemento

En la opción de menú Restore Resource, disponible para todos los usuarios que tengan role igual o superior a developer, se nos abrirá una pantalla en la que podremos ver el histórico de cambios para cualquier elemento al que tengamos acceso, restaurarlo e incluso modificar la versión actual.

Seleccionando un commit concreto, nos aparecerá un visor con las diferencias existentes entre el elemento actual (editable, a la derecha) y el elemento en el commit seleccionado (a la izquierda, no editable).

Una vez aquí, podremos restaurar la versión del commit (botón Restore), o editar la versión actual para mergear cambios, por ejemplo. Para editar la versión actual, modificaremos el contenido del elemento en el editor, y pulsaremos en Save Changes (cmd + s / ctrl + s).

Creación de un Tag de versión

En cualquier momento, podremos generar un tag de git y asignar la versión actual (SNAPSHOT) de todos los elementos versionables.

Restaurar la plataforma

Con esta funcionalidad también podemos restaurar todos los elementos de plataforma desde un repositorio git indicando un tag o branch.

También se puede realizar este proceso para migrar/promocionar entornos, por ejemplo, para llevarse los elementos de un entorno de desarrollo a uno de pre-producción.

Este proceso borrará todos los elementos versionables que no se encuentren en el repositorio Git.

Modificación de elementos desde repositorio Git

Es posible también modificar los elementos manualmente desde el repositorio, y después restaurarlos en plataforma, uno a uno o para restaurar el conjunto de los elementos de la plataforma.