Abordaje de un CI System

Pruebas en Fedora

Es relativamente fácil comenzar a probar artefactos de Fedora (construcciones de Koji, actualizaciones de Bodhi, etc.) y contribuir con los resultados de las pruebas para que luego puedan usarse para la activación, es decir, decidir si el artefacto probado debe promocionarse o no.

Aquí describimos los pasos necesarios para agregar un sistema CI nuevo.

¿Qué es un sistema CI (adecuado)?

Para proporcionar un buen flujo de trabajo y una buena experiencia de usuario, aquí se presentan algunos aspectos de los sistemas CI que han demostrado ser fructuosos:

  • Las pruebas son confiables (tasas bajas de falsos negativos y falsos positivos) y cubren historias importantes

  • Pueden ser contribuidas las pruebas (modelo de código abierto) e idealmente, son similares a otras pruebas, p.e. mediante el uso de marcos / lenguajes establecidos

  • Los resultados/notificaciones son fáciles de entender y ayudan a identificar errores rápidamente

  • Las pruebas son reproducibles, si es necesario, los artefactos de las ejecuciones de pruebas se almacenan para que los usuarios los consuman, como imágenes de máquina virtual

En resumen, ¡los resultados de las pruebas serían procesables directamente! Como desarrollador, necesito determinar rápidamente si la prueba o el código fallan, y luego solucionar el problema.

Construcciones de Pruebas y Portón

Flujo de trabajo de Portón

En el nivel más alto, el portón del flujo de trabajo consta de los siguientes pasos:

  • Submit build(s) of one or more package(s) (Koji), and an update containing those builds (Bodhi)

  • Disparador de sistemas CI para ejecutar pruebas (Fedora CI, Tu CI, etc.)

  • Recopilar resultados de los sistemas CI (ResultsDB)

  • Tomar una decisión (Onda verde)

  • Si la decisión es "aprobar", entonces deje que la compilación pase la puerta al repositorio principal (Bodhi)

Portón de Mensajes

Gating process is implemented as a set of services which interact with each other via message bus (Fedora Messaging).

Por lo tanto, para agregar una pieza (p.e., un sistema CI) al proceso, esencialmente necesitas comenzar a recibir y enviar mensajes a través de FedoraMessaging.

Como añadir un Sistema CI

Sistema CI en Fedora son entidades autónomas que normalmente necesitan gestionar las siguientes cosas:

  • disparar cuando ocurren ciertos eventos

  • pruebas actuales

  • publicación de resultados de pruebas

Activación y Prueba

Services in Fedora publish messages when various events occur and thus CI systems can trigger testing when for example a Bodhi update is created, or the builds in it change.

When either of those things happen, a new "koji-build-group.build.complete" message is published on the org.fedoraproject.prod.bodhi.update.status.testing.koji-build-group.build.complete topic.

The schema of these "koji-build-group.build.complete" messages is defined in the CI Messages specification.

You can design your CI system to trigger your tests in response to these messages. Some systems may have RabbitMQ listener code available for you to use (the current Fedora Messaging system is based on RabbitMQ). If you are using Jenkins you can try to follow the way the Fedora CI triggers work, e.g. the rpmdeplint trigger. If you can write the trigger code in Python, you can follow the fedora-messaging consumer documentation.

It’s of course possible to trigger testing on other types of events, not just Bodhi updates. You can find more Fedora message topics in the fedora-messaging documentation. Beware though, the list is incomplete.

Compartir Resultados de Prueba

CI systems should publish results to ResultsDB. This is required if you want the results to appear in the Bodhi web UI and for it to be possible to gate Bodhi updates on the results. Results should usually follow the format used by established systems like Fedora CI and openQA. In particular, for Bodhi gating to work, the 'item' for your result must be either a package NVR (in which case its 'type' must be 'koji_build') or an update ID like 'FEDORA-2026-be33882b5c' (in which case its type must be 'bodhi_update').

If your reporting code is in Python, you may find the resultsdb_conventions library a convenient helper for generating results in the expected formats for Fedora package, update or compose tests.

As well as final "results", CI systems can and likely should publish "results" that indicate test execution progress. The special 'outcomes' QUEUED and RUNNING exist for this purpose. Bodhi understands these results and displays them appropriately so people can see the current status of queued and running tests.

Publishing results to the production ResultsDB instance requires authentication. You will need to ask the Infrastructure team for credentials for this. It is a good idea to test your reporting code against a local ResultsDB instance first.

CI systems may also publish standardized CI messages so the progress of the testing can be observed and the results can be acted upon by other services in the Fedora infrastructure. There is a system that automatically forwards CI messages in certain formats to ResultsDB, so you may be able to avoid having explicit result reporting code. Note there is currently (as of 2026-07) a plan to decommission that system and stop publishing CI messages as a matter of course.

Hay cuatro tipos de mensajes que los sistemas CI deberían enviar:

  • test.queued - cuando hay un artefacto (una actualización de Bodhi, por ejemplo) en una cola esperando a ser probado

  • test.running - cuando la prueba está en curso

  • test.complete - cuando la prueba haya terminado

  • test.error – cuando las pruebas no pudieron comenzar o no pudieron finalizar debido a circunstancias externas (normalmente un error de infraestructura)

These messages have well-defined schemas. The schemas are part of the CI Messages specification.

For convenience, here are links to schemas for simple koji-build artifacts and fedora-update artifacts:

Identificadores de Prueba

When you send a "koji-build.test." or "fedora-update.test." message to the message bus, a result should be forwarded to ResultsDB by ci-resultsdb-listener, if the message contained the fields it expects (and the system is not explicitly excluded, as e.g. openQA is, because it does its own reporting). Later on you can refer to the stored test result in a Greenwave policy: "if test XYZ passed, let the build through the gate". Again, note this system may be dropped in future in favor of expecting CI systems to report directly to ResultsDB.

Por lo tanto, necesita identificadores únicos para los resultados de las pruebas.

Los identificadores de prueba se construyen a partir de tres partes: espacio de nombres de prueba, categoría de prueba y tipo de prueba.

In the koji-build and fedora-update message schemas, these variables are represented by namespace, category and type fields respectively.

El espacio de nombres siempre es un ID de su sistema CI con el nombre del tipo de artefacto, p.e.: fedora-ci.koji-build, u osci.pull-request.

Categoría que puedes elegir de una lista predefinida:

  • análisis estático

  • funcional

  • integración

  • validación

El tipo es una cadena arbitraria que puede definir según las características específicas de su sistema CI.

Es su responsabilidad como propietario del sistema CI mantener nombres consistentes para las pruebas en su espacio de nombres.

El identificador de prueba final podría verse así: fedora-ci.koji-build.tier0.functional

Enlaces útiles

Want to help? Learn how to contribute to Fedora Docs ›