buildstrap

See central hub for the end‑to‑end build system: builder-scripts/docs/system-overview.md

Bootstrap generation of CircleCI config.yml for RPM builds of the latest OS releases. Per-project configs are emitted by generate_circleci_config.py (settings.yml-driven) — the single CI-config writer. Verbatim templates were retired 2026-06-10 (see builder-scripts audits/2026-06-10-ci-config-writer-flipflop.md); only generated_config_nginx.yml (runtime-fetched by the nginx-modules cohort) and generated_config_self.yml (tag-triggered repos: ngm, fds, stack-scripts) remain.

Benefits

This allows for a more centralized and unified config.yml across many spec repositories. Furthermore, the config.yml itself becomes more dynamic and auto-maintained to have builds against recent operating systems.

Setup

The buildstrap regenerates the remaining templates and matrix files by running ~/buildstrap/cron.sh on the GetPageSpeed build server daily; per-project configs are regenerated by update-circle.sh / ensure-latest.sh invoking generate_circleci_config.py.

The list of operating systems supported can be updated in matrix.yml. The rpmbuilder images are tagged based on expected RPM dist tag of an operating system, e.g. getpagespeed/rpmbuilder:amzn2.

So matrix.yml file simply specifies the operating system label as understood by lastversion and their corresponding dist tag in order to build against the correct rpmbuilder image.

The matrix.json file contains all distros and their versions, used in various workflows.

As a special case, we also create generated_config_nginx.yml which creates workflows bound to the many branches of NGINX we build against: master (aka stable), mainline and plesk.

Example of implementation can be found in nginx-module-pagespeed-rpm.

Project setup

When every root-level spec in a project declares the main package as BuildArch: noarch, the generator emits only x86_64 workflows. The resulting RPM remains architecture-independent; x86_64 is simply the single build host. Mixed projects retain both x86_64 and aarch64 workflows. An explicit real archs: list in settings.yml overrides this detection. Legacy archs: [noarch] settings are accepted and normalized to x86_64.

Collection members normally build from the Git branch named by their collection key. A project that publishes into one collection channel from a different branch can set git_branch: while retaining the collection key for workflow names and enable_repos. The override is accepted only when exactly one collection branch is selected, so it cannot ambiguously remap a multi-branch project:

collection: varnish
git_branch: master

cd /rpm/project/dir
mkdir -p .circleci
curl https://raw.githubusercontent.com/GetPageSpeed/buildstrap/main/config.yml -o .circleci/config.yml

For memory/CPU intensive builds, run this instead:

cd /rpm/project/dir
mkdir -p .circleci
curl https://raw.githubusercontent.com/GetPageSpeed/buildstrap/main/config_large.yml -o .circleci/config.yml

In other words, copy config.yml (single branch project) or config_nginx.yml (NGINX module project) into .circleci/config.yml' of a spec project. Use config_large.yml` for "heavy" binaries which likely to exceed RAM on the small default CircleCi resource class.

In CircleCi, navigate to Project settings > Advanced -> Dynamic config using setup workflows.

Usage in a spec project repository

Refer to wrk example. In the static config.yml we use setup: true and fetch the recent generated_config.yml.

In this way, whenever the software is updated (GitHub repo is changed), we build it against desired set of operating systems.

However, when a new operating system is released, there is no automatic rebuild of the package. This can be implemented by triggering CircleCi workflows for individual spec projects using API.

For a software that is regularly updated, triggering workflows isn't required...

Anyway, triggering the build is possible via API like the following, e.g.:

curl --request POST \
  --url https://circleci.com/api/v2/project/github/GetPageSpeed/guetzli-rpm/pipeline \
  --header 'Circle-Token: xxx' \
  --header 'content-type: application/json'