Verified Commit b817ee24 authored by David Runge's avatar David Runge
Browse files

Merge remote-tracking branch 'origin/issues/10'

* origin/issues/10:
  README: Point to example configuration
  Add an example file for projects configuration
  README: Change openmetrics section into configuration subsection
  README: Move "Use" section below "Requirements" section
  README: Update JSON payload section
  README: Fix typo in Configuration section
  README: Add section about promotion artifact
  Fix releng example configuration
parents c47d82a4 70a06cdb
Pipeline #10289 passed with stages
in 53 seconds
......@@ -19,6 +19,11 @@ Requirements
The arch-release-promotion tool is Python based. All requirements are specified
in its `pyproject.toml <pyproject.toml>`_.
Use
===
After installation, refer to the output of ``arch-release-promotion -h``.
Configuration
=============
......@@ -27,7 +32,7 @@ The command-line tool ``arch-release-promotion`` makes use of two sources of con
* `makepkg.conf <https://man.archlinux.org/man/makepkg.conf.5>`_ is read from
any of its locations in the same priority as `makepkg
<https://man.archlinux.org/man/makepkg.8>`_ does.
All of the below can also be based to the tool via environment variables:
All of the below can also be passed to the tool via environment variables:
* ``GPGKEY`` is recognized for establishing which PGP key to use for signing
* ``PACKAGER`` is recognized for establishing who is doing the signature and
......@@ -44,23 +49,17 @@ The command-line tool ``arch-release-promotion`` makes use of two sources of con
<https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_
needs to provide write access for the target project.
* `projects.toml` is a configuration file that provides the configuration for a
* ``projects.toml`` is a configuration file that provides the configuration for a
project and its releases. Configuration files are read and merged with
descending priority from ``/etc/arch-release-promotion/projects.toml`` and
``$XDG_CONFIG_HOME/arch-release-promotion/projects.toml`` (which defaults to
``$HOME/.config/arch-release-promotion/projects.toml`` if
``$XDG_CONFIG_HOME`` is unset).
Please refer to the `example file <examples/projects.toml>`_ for further
Please refer to `examples/example.toml <examples/example.toml>`_ for further
reference in regards to the available options
Use
===
After installation, refer to the output of ``arch-release-promotion -h``.
Openmetrics
===========
-----------
If the upstream project offers an `openmetrics <https://openmetrics.io/>`_
based metrics file, the data from it can be used as additional information in
......@@ -69,7 +68,7 @@ the JSON payload.
The following metrics are considered.
Version metrics
---------------
^^^^^^^^^^^^^^^
Description and version information about e.g. packages can be derived from
``version_info`` metrics of type ``info``, that define a ``name``,
......@@ -98,7 +97,7 @@ The above metrics entry would result in the following JSON representation:
]
Size metrics
------------
^^^^^^^^^^^^
Artifact size information in MebiBytes (MiB) and description can be derived
from ``artifact_bytes`` metrics of type ``gauge``, that define a ``name`` and a
......@@ -127,7 +126,7 @@ The above metrics entry would result in the following JSON representation:
]
Amount metrics
--------------
^^^^^^^^^^^^^^
Information on the amount of something (e.g. packages) and description can be
derived from ``data_count`` metrics of type ``summary``, that define a ``name``
......@@ -155,8 +154,32 @@ The above metrics entry would result in the following JSON representation:
}
]
Promotion artifact
==================
The promotion artifact is a ZIP compressed file (``promotion.zip``), that is
uploaded to the project before its link is added to the release that it is
promoting.
The file contains one directory for each release type that the project offers.
In each release type directory there are is a **JSON payload**
(``<release_type>-<version>.json``), a directory
(``<release_type>-<version>/``) containing signatures for any files that have
been setup for detached signatures and optionally a torrent file
(``<release_type>-<version>.json``) that is created for the release type's
build artifacts *and* the detached signatures contained in the promotion
artifact.
.. code::
example
├── example-0.1.0
│   └── artifact.tar.gz.sig
├── example-0.1.0.json
└── example-0.1.0.torrent
JSON payload
============
------------
The promotion of a release encompasses one or more JSON payloads, that describe
each release type in the release.
......@@ -164,51 +187,56 @@ each release type in the release.
.. code:: json
{
"developer": "Foobar McFooface <foobar@mcfooface.com>",
"files": ["something.txt", "something.txt.sig"],
"version_metrics": [
"amount_metrics": [
{
"my-package": {
"description": "Version of my-package used for build",
"version": "1.0.0-1"
}
"name": "foo",
"description": "The amount of packages in foo",
"size": 369
}
],
"developer": "Foobar McFooface <foobar@mcfooface.com>",
"files": ["something.txt", "something.txt.sig"],
"name": "foo",
"pgp_public_key": "SOMEONESPGPKEYID",
"size_metrics": [
{
"foo": {
"description": "Size of foo in MiB",
"size": 832
}
"name": "foo",
"description": "Size of foo in MiB",
"size": 832
}
],
"amount_metrics": [
"torrent_file": "foo-0.1.0.torrent",
"version_metrics": [
{
"foo": {
"description": "The amount of packages in foo",
"size": 369
}
"name": "my-package",
"description": "Version of my-package used for build",
"version": "1.0.0-1"
}
],
"name": "foo",
"pgp_public_key": "SOMEONESPGPKEYID",
"torrent_file": "foo-0.1.0.torrent",
"version": "0.1.0"
}
* ``amount_metrics``: A list of objects that describe the amount of something
(optional). The list depends on whether the project's configuration defines
``amount_metrics`` and whether those metrics are available in the specific
release.
* ``developer``: The full uid of the person promoting (and optionally signing
artifacts in) the release type.
* ``files``: A list of files in the release type.
* ``info`` (optional): Additional info about the (creation of) the release
type. The value depends on whether configuration of the release type defines
at least one value in its list of ``info_metrics`` and whether this is found
in the release's metrics file.
* ``name``: The name of the release type.
* ``pgp_public_key``: The PGP key ID of the key signing files in the release
type.
* ``size_metrics``: A list of objects that describe the size of something
(optional). The list depends on whether the project's configuration defines
``size_metrics`` and whether those metrics are available in the specific
release.
* ``torrent_file`` (optional): The name of a torrent file created for the
release type. The value depends on whether the configuration for the release
type sets ``create_torrent`` to ``True``.
* ``version_metrics``: A list of objects that describe the version of something
(optional). The list depends on whether the project's configuration defines
``version_metrics`` and whether those metrics are available in the specific
release.
* ``version``: The version of the release type.
License
......
# A list of tables that defines settings for each project.
# Each project defines a [[projects]] list of tables and its individual
# settings.
[[projects]]
# The group and name of the project.
name = "group/example"
# The name of the job that provides build artifacts for releases.
job_name = "build"
# The name of a metrics file that resides in the release's output directory
# (optional).
metrics_file = "metrics.txt"
# The name of the directory in which the release's artifacts reside.
output_dir = "output"
# A list of release types and their configurations.
releases = [
# Each release type is described as an object.
# NOTE: TOML does not allow a trailing comma in an object (the last attribute
# does not have a trailing comma).
{
# A list of names matching openmetrics labels, that track amounts of
# something, to be extracted from the metrics file (optional).
amount_metrics = ["example_amount"],
# Whether to create a torrent file for the release type.
create_torrent = true,
# A list of file extensions (only the last part of the extension is matched
# against!) for which to create detached signatures.
extensions_to_sign = [".txt"],
# The name of the release type.
name = "example_a",
# A list of names matching openmetrics labels, that track the size of
# something, to be extracted from the metrics file (optional).
size_metrics = ["example_size"],
# A list of names matching openmetrics labels, that track the version of
# something, to be extracted from the metrics file (optional).
version_metrics = ["example_version"]
},
]
......@@ -5,34 +5,65 @@ metrics_file = "metrics.txt"
output_dir = "output"
releases = [
{
name = "bootstrap",
info_metrics = ["archiso"],
extensions_to_sign = [".tar.gz"],
amount_metrics = [
"bootstrap",
],
create_torrent = true,
extensions_to_sign = [".gz"],
name = "bootstrap",
size_metrics = [
"bootstrap",
],
version_metrics = [
"archiso",
"pacman",
"systemd",
]
},
{
extensions_to_sign = [".efi", ".lkrn", ".pxe"],
name = "ipxe",
version_metrics = [
"archiso",
"ipxe",
],
extensions_to_sign = [".efi", ".lkrn", ".pxe"]
]
},
{
amount_metrics = [
"iso",
],
create_torrent = true,
name = "iso",
extensions_to_sign = [".iso"],
size_metrics = [
"eltorito_efi_image",
"initramfs",
"iso",
],
version_metrics = [
"archinstall",
"archiso",
"linux",
],
extensions_to_sign = [".iso"],
create_torrent = true,
"pacman",
"systemd",
]
},
{
amount_metrics = [
"netboot",
],
extensions_to_sign = [],
name = "netboot",
size_metrics = [
"netboot",
"initramfs",
],
version_metrics = [
"archinstall",
"archiso",
"linux",
],
extensions_to_sign = []
"pacman",
"systemd",
]
},
]
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment