onvif
RFC Adding two Github actions to generate the PDF files
This draft PR is a Request For Comments from the TC, to evaluate the possibility of using GitHub Actions to generate the PDF files of the specifications. This works on every service but the PTZ service, which has special needs due to the formulas. The PTZ specs will still be manually generated without Apache fop. The correct automatic generation of the PTZ service will be addressed in a future PR, once a solution will be available.
What
This PR includes two workflows:
-
generate-pdf-files-from-development.yaml: triggered by a push todevelopment, it generates the PDF files for all the specs. At the end of execution, it creates an artifact consisting of a zip file with the generated PDF files. The retention of artifacts will be of 30 days and the name of the artifacts will be in the format `ONVIF-specs-. -
generate-pdf-files-from-tag.yaml: same as the previous one, but triggered by pushing a tag to the repository in the format ofYY.MM. The retention period of the generated artifacts is 90 days and the name of the artifacts will be in the formatONVIF-specs-YY.MM, matching the tag.
Why
Since ONVIF switched to DocBook, the TC always leveraged Java 8, Fop and Xalan-j to generated the PDF files. Unfortunately, as the development of Java progressed, constraints due to cybersecurity were added and the only way to keep compiling the files is to use Java 8, Fop 2.9 and Xalan-j-2.7-1 or older software and to relax multiple security constrains for the Java virtual machine.
Since running old version of packages with relaxed security constraints is not good practice, I propose to generate PDF files using disposable containers. Moreover, since the configuration for the runners is in the action files, anyone able to commit to development or to push a tag will be able to generate the files without wasting time tweaking and posing at risk his computer.
Cost
Github actions is free for public repositories, such as this one.
@ocampana-videotec thank you for taking the time to do this work. I will wait until the TC Meeting to hear the rest of the discussion as per the suggestion in the emails conversation.
Update for digital signing
After having explored different options, I cam to the conclusion that for our need the usage of GnuPG can be enough. For each PDF file, we are going to generate a .pdf.sig file with the signature. Those files will be available on the ONVIF website, together with the public key for provenance verification. The file with the public key will be publish on the ONVIF website.
@ocampana-videotec this is a lot to work through and understand and I don't mind saying I am a little confused. I have a few basic questions that came to mind;
- These 161 files are all pre-existing files that were used to generate standards pdf files and you created 2 new ".yaml" files to manage and regenerate the "PDF" standards files and Digitally sign each using GnuPG tool ? Am I correct?
- Will this solve the loss of support for the ".xslt" style sheets for rendering the ".WSDL" & ".XSD" files or is that another problem to solve?
@ocampana-videotec this is a lot to work through and understand and I don't mind saying I am a little confused. I have a few basic questions that came to mind;
- These 161 files are all pre-existing files that were used to generate standards pdf files and you created 2 new ".yaml" files to manage and regenerate the "PDF" standards files and Digitally sign each using GnuPG tool ? Am I correct?
- Will this solve the loss of support for the ".xslt" style sheets for rendering the ".WSDL" & ".XSD" files or is that another problem to solve?
For question 1: the 161 pre-existing files are those currently used to generate the PDFs from the docbook specs. Until the generation of the PDF files, nothing changes. My proposal, to guarantee authenticity, is to digitally sign the PDF files using GnuPG.
For question 2: no, this will not solve that part. We will address this issue in January 2026
Should signing be a separate job? Any PDF in the workspace gets signed. Scope to output directory?
Should signing be a separate job? Any PDF in the workspace gets signed. Scope to output directory?
for ease of use, all the PDF files are going to be signed within the same job, but only when merging in master.
Ottavio
@ocampana-videotec this is a lot to work through and understand and I don't mind saying I am a little confused. I have a few basic questions that came to mind;
- These 161 files are all pre-existing files that were used to generate standards pdf files and you created 2 new ".yaml" files to manage and regenerate the "PDF" standards files and Digitally sign each using GnuPG tool ? Am I correct?
- Will this solve the loss of support for the ".xslt" style sheets for rendering the ".WSDL" & ".XSD" files or is that another problem to solve?
For question 1: the 161 pre-existing files are those currently used to generate the PDFs from the docbook specs. Until the generation of the PDF files, nothing changes. My proposal, to guarantee authenticity, is to digitally sign the PDF files using GnuPG.
For question 2: no, this will not solve that part. We will address this issue in January 2026
Thank you @ocampana-videotec .
@ocampana-videotec just one question do you need us to perform an approve on this PR before we release 25.12 or is this PR as you said purely for RFC purposes?
This is to trigger the discussion, and as you see it was open as draft PR. I will turn it into a regular PR, so that you can approve, and I'll merge,
This is to trigger the discussion, and as you see it was open as draft PR. I will turn it into a regular PR, so that you can approve, and I'll merge,
I am happy to wait, there are I am sure many more comments to cone esp. when we have our TC meeting. I was just checking.
Added the draft watermark and commented out signing, as agreed during the TC meeting. We are now ready to merge