Gentoo Build Publisher: GraphQL Interface

It's been four years since I've talked about Gentoo Build Publisher's GraphQL API. The 3.2 release contains a number of improvements worth mentioning.

The GraphQL API is mostly intended to support the CLI, however it can also be used for other purposes. Plugins can also extend the API as we'll see.

GraphiQL

Through coincidence of having removed a dependency, the GraphQL web UI, accessible from accessing the GraphQL endpoint in the browser, has replaced GraphQL Playground with GraphiQL, a more up-to-date interface.

stats

Still in development, there is a stats query to show GBP statistics, similar to what you see on the dashboard ui:

{
  stats {
    machineInfo {
      machine
      buildCount
      totalPackageSize
    }
  }
}

{
  "data": {
    "stats": {
      "machineInfo": [
        {
          "machine": "lighthouse",
          "buildCount": 32,
          "totalPackageSize": "74415903858"
        },
        {
          "machine": "polaris",
          "buildCount": 29,
          "totalPackageSize": "52165410936"
        },
        {
          "machine": "gbp",
          "buildCount": 28,
          "totalPackageSize": "8027929733"
        },
...

Note: totalPackageSize is given as a String instead of Int because GrapQL's Int type is specified as a 32-bit signed integer and package sizes will typically fall outside of that range.

packagesByDay

You can now query the packages built on a machine by day packages" thanks to having connected the stats layer with the GraphQL layer. For example:

{
  machines(names: ["mediaserver"]) {
    machine
    packagesByDay {
      date
      packages {
        cpv
      }
    }
  }
}

The response looks like:

{
  "data": {
    "machines": [
      {
        "machine": "mediaserver",
        "packagesByDay": [
          {
            "date": "2025-10-09",
            "packages": [
              {
                "cpv": "dev-python/platformdirs-4.5.0"
              },
              {
                "cpv": "sys-kernel/linux-headers-6.17-r1"
              }
            ]
          },
          {
            "date": "2025-10-07",
            "packages": [
              {
                "cpv": "app-crypt/gnupg-2.5.12-r1"
              },
              {
                "cpv": "dev-lang/python-3.13.8"
              },
              {
                "cpv": "dev-lang/python-3.14.0"
              },
...

packageDetail

The Build type already had a packages field that returned a list of packages in that build. However it only listed the CPVs (and optionally CPVBs). There is now a new field, packageDetail that can show any field on the Package:

{
  latest(machine: "base") {
    id
    packageDetail {
      cpv
      size
      url
      path
      repo
    }
  }
}

{
  "data": {
    "latest": {
      "id": "base.1791",
      "packageDetail": [
        {
          "cpv": "acct-group/adm-0-r3",
          "size": 20480,
          "url": "/machines/base/builds/1791/packages/acct-group/adm/adm-0-r3-1",
          "path": "acct-group/adm/adm-0-r3-1.gpkg.tar",
          "repo": "gentoo"
        },
        {
          "cpv": "acct-group/audio-0-r3",
          "size": 20480,
          "url": "/machines/base/builds/1791/packages/acct-group/audio/audio-0-r3-1",
          "path": "acct-group/audio/audio-0-r3-1.gpkg.tar",
          "repo": "gentoo"
        },
        {
          "cpv": "acct-group/cdrom-0-r3",
          "size": 20480,
          "url": "/machines/base/builds/1791/packages/acct-group/cdrom/cdrom-0-r3-1",
          "path": "acct-group/cdrom/cdrom-0-r3-1.gpkg.tar",
          "repo": "gentoo"
        },
        {
          "cpv": "acct-group/dialout-0-r3",
          "size": 20480,
          "url": "/machines/base/builds/1791/packages/acct-group/dialout/dialout-0-r3-1",
          "path": "acct-group/dialout/dialout-0-r3-1.gpkg.tar",
          "repo": "gentoo"
        },
...

files & fileStats

If the gbp-fl plugin is installed, you can even get the files in the package:

{
  latest(machine: "polaris") {
    id
    built
    submitted
    completed
    packagesBuilt {
      cpv
      repo
      path
      size
      files {
        path
        size
        timestamp
      }
    }
  }
}

{
  "data": {
    "build": {
      "id": "polaris.35644",
      "built": "2025-10-09T17:35:08.549000+00:00",
      "submitted": "2025-10-09T17:37:22.900685+00:00",
      "completed": "2025-10-09T17:37:57.401818+00:00",
      "packagesBuilt": [
        {
          "cpv": "sec-keys/openpgp-keys-llvm-21.1.3",
          "repo": "gentoo",
          "path": "sec-keys/openpgp-keys-llvm/openpgp-keys-llvm-21.1.3-2.gpkg.tar",
          "size": 20480,
          "files": [
            {
              "path": "/usr/share/openpgp-keys/llvm.asc",
              "size": 6381,
              "timestamp": "2025-10-09T17:35:48+00:00"
            }
          ]
        }
      ]
    }
  }
}

And also with the plugin the MachineSummary type gains a fileStats field:

{
  machines(names: ["polaris"]) {
    machine
    buildCount
    packageCount
    fileStats {
      total
      perBuild
    }
  }
}

{
  "data": {
    "machines": [
      {
        "machine": "polaris",
        "buildCount": 31,
        "packageCount": 33081,
        "fileStats": {
          "total": 9078399,
          "perBuild": 292851
        }
      }
    ]
  }
}

There are other changes as well, for example a new TagInfo type has been added to MachineSummary. In addition to the tags field that is a list of String, the TagInfo field returns an array of type TagInfo which includes both the name of the tag as well as the Build object possessing the tag.

These additions provide an unprecedented way to not only collectively query data about all your Gentoo machines, but also get this data on a build-by-build basis.

Pages