pingou / fedora-ci / messages

Forked from fedora-ci/messages 4 years ago
Clone
README.md

CI Messages

This repo specifies details of messages, which should be sent out by Upstream/Downstream CI systems to fedmsg/UMB on events related to artifacts testing. Currently there is low unification of these messages and there are various types of messages sent out by the CI systems. Unification will make it possible to build simpler services which will provide useful features for everyone.

Specification

The message format is described by JSON Schema. In order to allow better readability and review we store the schemas in the YAML format. Use make convert to convert the spec into JSON.

Repository contains also a set of example messages which can be validated against the specification using make test. Use make clean to clean up all temporary files. Run make to convert spec, validate messages and clean up in a single step.

Note: Make sure that python3-jsonschema and python3-anymarkup are installed on your system when converting specification and validating examples.

Validation

When implementing CI Messages specification in your application it is a good idea to validate generated messages against the schema. Make sure that schemas are converted and run the validate.py script to ensure your message.json file has proper format:

make convert
./scripts/validate.py schemas/brew-build.test.complete.json message.json

Examples

Examples should have exactly the same name as the schema against which they should be validated. Use optional suffix starting with the "+" sign to test multiple examples against a single schema, for example like this:

the-schema-name+simple.json
the-schema-name+complex.json

Virtual topic namespace

The messages will use unique UMB virtual topic namespaces to mitigate collisions with other systems:

UMB: /topic/VirtualTopic.eng.ci

fedmsg:
  org.fedoraproject.prod.ci
  org.centos.prod.ci

For all the tests on all the artifacts the systems will use this topic naming convention:

UMB: /topic/VirtualTopic.eng.ci.<artifact>.<event>.{queued,running,complete,error}
fedmsg: org.fedoraproject.prod.ci.<artifact>.<event>.{queued,running,complete,error}

where artifact is one of the defined build artifacts, for example:

  • brew-build - scratch or non-scratch rpm build from Brew build system
  • container-image - generic container image build
  • koji-build - scratch or non-scratch rpm build from Koji build system
  • redhat-container-image - a container image build from OSBS, metadata accessible via Brew build system
  • redhat-module - an Red Hat MBS module build

where event is one of the recognized events, for example:

  • build - tracking progress of building artifacts
  • test - for testing progression and results
  • gate - for gating events of artifacts, i.e. events blocking progression of the artifact in the release pipeline

Message Anatomy

All data should be stored in the body of the message. Additional fields can be added to the messages as required by the senders, although it is advised to document them here.

Syntax requirements for field names:

  • Use only characters [a-z0-9_]
  • No spaces are allowed in the name of the field
  • For separation of multi-word strings in field names use the underscore character

Syntax requirements for field values:

  • Boolean value must be one of true or false
  • If a field contains multiple values a list must be used for it e.g. recipients: ["mvadkert", "optak"]. In case of an empty field, this needs to be and empty list: []

Links