From 1a4a5c01ea15f11119206bf4ee31884105d79ec0 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Thu, 9 Jan 2025 14:59:01 +0000 Subject: [PATCH 1/4] feat(ruleset): expose subcomponents --- .releaserc.yaml | 16 +++++++-------- templates/config/README.md | 20 +++++++++++++++++++ .../config.yml => config/template.yml} | 0 templates/os/README.md | 19 ++++++++++++++++++ templates/{ruleset/os.yml => os/template.yml} | 0 templates/ruleset/template.yml | 8 ++++---- templates/semantic-release/README.md | 18 +++++++++++++++++ .../template.yml} | 0 templates/version/README.md | 18 +++++++++++++++++ .../version.yml => version/template.yml} | 0 10 files changed, 87 insertions(+), 12 deletions(-) create mode 100644 templates/config/README.md rename templates/{ruleset/config.yml => config/template.yml} (100%) create mode 100644 templates/os/README.md rename templates/{ruleset/os.yml => os/template.yml} (100%) create mode 100644 templates/semantic-release/README.md rename templates/{ruleset/semantic-release.yml => semantic-release/template.yml} (100%) create mode 100644 templates/version/README.md rename templates/{ruleset/version.yml => version/template.yml} (100%) diff --git a/.releaserc.yaml b/.releaserc.yaml index efc2cc6..ebf6b1f 100644 --- a/.releaserc.yaml +++ b/.releaserc.yaml @@ -24,15 +24,15 @@ plugins: frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" - - filepath: "templates/ruleset/os.yml" + - filepath: "templates/os/template.yml" frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" - - filepath: "templates/ruleset/version.yml" + - filepath: "templates/version/template.yml" frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" - - filepath: "templates/ruleset/config.yml" + - filepath: "templates/config/template.yml" frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" @@ -40,7 +40,7 @@ plugins: frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" - - filepath: "templates/ruleset/semantic-release.yml" + - filepath: "templates/semantic-release/template.yml" frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" @@ -50,11 +50,11 @@ plugins: - "CHANGELOG.md" - "templates/bazelisk.yml" - "templates/ruleset/.job.yml" - - "templates/ruleset/os.yml" - - "templates/ruleset/version.yml" - - "templates/ruleset/config.yml" + - "templates/os/template.yml" + - "templates/version/template.yml" + - "templates/config/template.yml" - "templates/ruleset/template.yml" - - "templates/ruleset/semantic-release.yml" + - "templates/semantic-release/template.yml" - path: "@semantic-release/bzlmod" source: prefix: "${CI_PROJECT_NAME}-v${version}" diff --git a/templates/config/README.md b/templates/config/README.md new file mode 100644 index 0000000..b6b328f --- /dev/null +++ b/templates/config/README.md @@ -0,0 +1,20 @@ +# `config` + +> A set of jobs for testing different [Bazel configurations] + +## Getting Started + +```yaml +include: + - component: "${CI_SERVER_HOST}/ci/component/bazelisk/config@" +``` + +Select a `` according to [CI component versions]. + +## Requirements + +- There are `local`/`remote` configurations in `.bazelrc.ci` +- The `e2e` directory exists for end-to-end testing of the ruleset + +[Bazel configurations]: https://bazel.build/extending/config +[CI component versions]: https://docs.gitlab.com/ee/ci/components/#component-versions diff --git a/templates/ruleset/config.yml b/templates/config/template.yml similarity index 100% rename from templates/ruleset/config.yml rename to templates/config/template.yml diff --git a/templates/os/README.md b/templates/os/README.md new file mode 100644 index 0000000..8227fc0 --- /dev/null +++ b/templates/os/README.md @@ -0,0 +1,19 @@ +# `os` + +> A set of jobs for testing different operating systems + +## Getting Started + +```yaml +include: + - component: "${CI_SERVER_HOST}/ci/component/bazelisk/os@" +``` + +Select a `` according to [CI component versions]. + +## Requirements + +- The `e2e` directory exists for end-to-end testing of the ruleset +- The runner tags `linux`, `windows` and `macos` exist + +[CI component versions]: https://docs.gitlab.com/ee/ci/components/#component-versions diff --git a/templates/ruleset/os.yml b/templates/os/template.yml similarity index 100% rename from templates/ruleset/os.yml rename to templates/os/template.yml diff --git a/templates/ruleset/template.yml b/templates/ruleset/template.yml index f7937a3..a5f9404 100644 --- a/templates/ruleset/template.yml +++ b/templates/ruleset/template.yml @@ -46,7 +46,7 @@ spec: description: "The operating systems to test on." --- include: - - local: "/templates/ruleset/version.yml" + - local: "/templates/version/template.yml" inputs: image: "$[[inputs.image]]" tag: "$[[inputs.tag]]" @@ -54,7 +54,7 @@ include: needs: $[[inputs.needs]] roots: $[[inputs.roots]] versions: $[[inputs.versions]] - - local: "/templates/ruleset/config.yml" + - local: "/templates/config/template.yml" inputs: image: "$[[inputs.image]]" tag: "$[[inputs.tag]]" @@ -62,7 +62,7 @@ include: needs: $[[inputs.needs]] roots: $[[inputs.roots]] configs: $[[inputs.configs]] - - local: "/templates/ruleset/os.yml" + - local: "/templates/os/template.yml" inputs: image: "$[[inputs.image]]" tag: "$[[inputs.tag]]" @@ -70,7 +70,7 @@ include: needs: $[[inputs.needs]] roots: $[[inputs.roots]] oses: $[[inputs.oses]] - - local: "/templates/ruleset/semantic-release.yml" + - local: "/templates/semantic-release/template.yml" inputs: image: "$[[inputs.image]]" tag: "$[[inputs.tag]]" diff --git a/templates/semantic-release/README.md b/templates/semantic-release/README.md new file mode 100644 index 0000000..8e4f8f0 --- /dev/null +++ b/templates/semantic-release/README.md @@ -0,0 +1,18 @@ +# `semantic-release` + +> A set of jobs for releasing a Bazel ruleset + +## Getting Started + +```yaml +include: + - component: "${CI_SERVER_HOST}/ci/component/bazelisk/semantic-release@" +``` + +Select a `` according to [CI component versions]. + +## Requirements + +- `semantic-release` is configured for the project + +[CI component versions]: https://docs.gitlab.com/ee/ci/components/#component-versions diff --git a/templates/ruleset/semantic-release.yml b/templates/semantic-release/template.yml similarity index 100% rename from templates/ruleset/semantic-release.yml rename to templates/semantic-release/template.yml diff --git a/templates/version/README.md b/templates/version/README.md new file mode 100644 index 0000000..ea02501 --- /dev/null +++ b/templates/version/README.md @@ -0,0 +1,18 @@ +# `version` + +> A set of jobs for testing different Bazel versions + +## Getting Started + +```yaml +include: + - component: "${CI_SERVER_HOST}/ci/component/bazelisk/version@" +``` + +Select a `` according to [CI component versions]. + +## Requirements + +- The `e2e` directory exists for end-to-end testing of the ruleset + +[CI component versions]: https://docs.gitlab.com/ee/ci/components/#component-versions diff --git a/templates/ruleset/version.yml b/templates/version/template.yml similarity index 100% rename from templates/ruleset/version.yml rename to templates/version/template.yml -- GitLab From c6f093bb1a41a72a9014ba9f604995587697f0aa Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Mon, 13 Jan 2025 09:38:11 +0000 Subject: [PATCH 2/4] fix(semantic-release): inline default for `needs` The default only made sense for the `ruleset` template. When using the `semantic-release` in isolation, an empty array is a better default. It also seeems that `os` was missing, which is likely leftover from 0fe682fc005c49b7f9774e175f0eaf6f5080fd35. --- templates/ruleset/template.yml | 4 ++++ templates/semantic-release/template.yml | 4 +--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/templates/ruleset/template.yml b/templates/ruleset/template.yml index a5f9404..a1bc5dc 100644 --- a/templates/ruleset/template.yml +++ b/templates/ruleset/template.yml @@ -74,3 +74,7 @@ include: inputs: image: "$[[inputs.image]]" tag: "$[[inputs.tag]]" + needs: + - config + - version + - os diff --git a/templates/semantic-release/template.yml b/templates/semantic-release/template.yml index 040259e..9322a47 100644 --- a/templates/semantic-release/template.yml +++ b/templates/semantic-release/template.yml @@ -8,9 +8,7 @@ spec: description: "Open container image (OCI) tag for the image." needs: type: array - default: - - config - - version + default: [] description: "Jobs to run before the `semantic-release` job." --- include: -- GitLab From def9d82ddda389e1a57bd1c93ea7660ce510d4d0 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Mon, 13 Jan 2025 09:45:48 +0000 Subject: [PATCH 3/4] feat(semantic-release): support `extends` Leftover from 29e2a5461be60e3dbfacc3ae07b27f65e8a6d915. --- templates/semantic-release/template.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/templates/semantic-release/template.yml b/templates/semantic-release/template.yml index 9322a47..b0bbbfa 100644 --- a/templates/semantic-release/template.yml +++ b/templates/semantic-release/template.yml @@ -6,6 +6,11 @@ spec: tag: default: latest description: "Open container image (OCI) tag for the image." + extends: + type: array + default: + - .job + description: "Jobs to extend." needs: type: array default: [] @@ -19,7 +24,7 @@ include: # TODO: switch this out for `rules_semantic_release` semantic-release: - extends: .job + extends: $[[inputs.extends]] stage: .post image: node:lts needs: $[[inputs.needs]] -- GitLab From d6f7275a3b318e599a3cb1e61ebaa26a71fc8db1 Mon Sep 17 00:00:00 2001 From: Alex Tercete Date: Mon, 13 Jan 2025 14:47:03 +0000 Subject: [PATCH 4/4] style(bazelisk): convert from file to folder template For consistency with the new templates. The top-level README was moved under the `bazelisk` component. --- .releaserc.yaml | 4 +- .reuse/dep5 | 2 +- README.md | 112 ++---------------- templates/bazelisk/README.md | 110 +++++++++++++++++ .../{bazelisk.yml => bazelisk/template.yml} | 0 templates/ruleset/.job.yml | 2 +- 6 files changed, 123 insertions(+), 107 deletions(-) create mode 100644 templates/bazelisk/README.md rename templates/{bazelisk.yml => bazelisk/template.yml} (100%) diff --git a/.releaserc.yaml b/.releaserc.yaml index ebf6b1f..e38915a 100644 --- a/.releaserc.yaml +++ b/.releaserc.yaml @@ -16,7 +16,7 @@ plugins: - "@semantic-release/bzlmod" - path: "@semantic-release/yq" assets: - - filepath: "templates/bazelisk.yml" + - filepath: "templates/bazelisk/template.yml" frontMatter: "process" expression: |- .spec.inputs.tag.default = "${nextRelease.version}" @@ -48,7 +48,7 @@ plugins: assets: - "MODULE.bazel" - "CHANGELOG.md" - - "templates/bazelisk.yml" + - "templates/bazelisk/template.yml" - "templates/ruleset/.job.yml" - "templates/os/template.yml" - "templates/version/template.yml" diff --git a/.reuse/dep5 b/.reuse/dep5 index 14408a2..cdabe09 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -9,7 +9,7 @@ Files: */test/*.yaml *.bzl *.sh - templates/bazelisk.yml + templates/*.yml Copyright: 2024 Arm Ltd. License: MIT diff --git a/README.md b/README.md index 2d6ba69..9d3e614 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,16 @@ # `ci/component/bazelisk` -> A GitLab CI component for running Bazel builds +> A set of GitLab CI components for running Bazel builds ## Getting Started -Add the CI component to the `.gitlab-ci.yml`: +Most users should choose between the [`ruleset`] (opinionated) and the [`bazelisk`] (fully-customizable) components. -```yaml -include: - - component: "${CI_SERVER_HOST}/ci/component/bazelisk/bazelisk@" -``` +The [`config`], [`version`], [`os`] and [`semantic-release`] are subcomponents of [`ruleset`], and are exposed for users wanting to opt-out of any of the default jobs. -Add a job that extends the `.bazelisk` template to recursively test the project: - -```yaml -test: - extends: .bazelisk -``` - -## Variables - -The template has some environment variables that can customise the job behaviour. - -### `ROOT` - -To run `bazelisk` in multiple root directories: - -```yaml -test: - extends: .bazelisk - parallel: - matrix: - - ROOT: - - . - - e2e -``` - -### `USE_BAZEL_VERSION` - -`bazelisk` will download a version of Bazel as described in the [documentation][bazelisk-download]. - -To run against multiple versions of Bazel: - -```yaml -test: - extends: .bazelisk - parallel: - matrix: - - USE_BAZEL_VERSION: - - 6.3.1 - - 7.0.0 -``` - -## Open Container Image (OCI) - -The default image has `bazelisk` available on `PATH` and a minimal set of core utilities to satisfy GitLab CI job bring-up and built-in Bazel scripts. - -The intention is that this image helps prove the hermeticity of a Bazel build as all tools will need to be resolved hermetically. - -To use a different base image, override the image input for the component: - -```yaml -include: - - component: gitlab.arm.com/ci/component/bazelisk@ - inputs: - image: host.com/some/registry/bazelisk - tag: latest -``` - -### OCI Local Usage - -Assuming the current working directory is the root of the project to test, run the following: - -```shell -$ podman run \ - -v $PWD:/mnt/src \ - -w /mnt/src \ - --rm \ - -it registry.gitlab.arm.com/ci/component/bazelisk:1.0.0-beta.2 \ - /bin/sh -sh-5.2$ bazelisk test //... -``` - -## YAML References - -The `.bazelisk` template provides a simple way to invoke `bazelisk` in a job. - -GitLab CI has a [`!reference`][gitlab-ci-reference] feature that allows parts of a template to be re-used in a fine grained way. - -It is recommended to use this feature to build up a custom `bazelisk` job by using `!reference` to select parts of the `.bazelisk` image that are relevant. - -Commonly, this is used to customise the `script` section of a job but still re-using parts of the `.bazelisk` template script: - -```yaml -custom: - extends: - - .bazelisk - - .credentials - before_script: - - !reference [.bazelisk, before_script] - - !reference [.credentials, before_script] - script: - - bazelisk build //... - - bazelisk run //... -``` - -[package-registry]: https://gitlab.arm.com/ci/component/bazelisk/-/packages -[gitlab-ci-reference]: https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html#reference-tags -[bazelisk-download]: https://github.com/bazelbuild/bazelisk#how-does-bazelisk-know-which-bazel-version-to-run +[`ruleset`]: templates/ruleset/ +[`bazelisk`]: templates/bazelisk/ +[`config`]: templates/config/ +[`version`]: templates/version/ +[`os`]: templates/os/ +[`semantic-release`]: templates/semantic-release/ diff --git a/templates/bazelisk/README.md b/templates/bazelisk/README.md new file mode 100644 index 0000000..1cc1ea6 --- /dev/null +++ b/templates/bazelisk/README.md @@ -0,0 +1,110 @@ +# `bazelisk` + +> A component for running Bazel builds + +## Getting Started + +Add the CI component to the `.gitlab-ci.yml`: + +```yaml +include: + - component: "${CI_SERVER_HOST}/ci/component/bazelisk/bazelisk@" +``` + +Add a job that extends the `.bazelisk` template to recursively test the project: + +```yaml +test: + extends: .bazelisk +``` + +## Variables + +The template has some environment variables that can customise the job behaviour. + +### `ROOT` + +To run `bazelisk` in multiple root directories: + +```yaml +test: + extends: .bazelisk + parallel: + matrix: + - ROOT: + - . + - e2e +``` + +### `USE_BAZEL_VERSION` + +`bazelisk` will download a version of Bazel as described in the [documentation][bazelisk-download]. + +To run against multiple versions of Bazel: + +```yaml +test: + extends: .bazelisk + parallel: + matrix: + - USE_BAZEL_VERSION: + - 6.3.1 + - 7.0.0 +``` + +## Open Container Image (OCI) + +The default image has `bazelisk` available on `PATH` and a minimal set of core utilities to satisfy GitLab CI job bring-up and built-in Bazel scripts. + +The intention is that this image helps prove the hermeticity of a Bazel build as all tools will need to be resolved hermetically. + +To use a different base image, override the image input for the component: + +```yaml +include: + - component: gitlab.arm.com/ci/component/bazelisk@ + inputs: + image: host.com/some/registry/bazelisk + tag: latest +``` + +### OCI Local Usage + +Assuming the current working directory is the root of the project to test, run the following: + +```shell +$ podman run \ + -v $PWD:/mnt/src \ + -w /mnt/src \ + --rm \ + -it registry.gitlab.arm.com/ci/component/bazelisk:1.0.0-beta.2 \ + /bin/sh +sh-5.2$ bazelisk test //... +``` + +## YAML References + +The `.bazelisk` template provides a simple way to invoke `bazelisk` in a job. + +GitLab CI has a [`!reference`][gitlab-ci-reference] feature that allows parts of a template to be re-used in a fine grained way. + +It is recommended to use this feature to build up a custom `bazelisk` job by using `!reference` to select parts of the `.bazelisk` image that are relevant. + +Commonly, this is used to customise the `script` section of a job but still re-using parts of the `.bazelisk` template script: + +```yaml +custom: + extends: + - .bazelisk + - .credentials + before_script: + - !reference [.bazelisk, before_script] + - !reference [.credentials, before_script] + script: + - bazelisk build //... + - bazelisk run //... +``` + +[package-registry]: https://gitlab.arm.com/ci/component/bazelisk/-/packages +[gitlab-ci-reference]: https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html#reference-tags +[bazelisk-download]: https://github.com/bazelbuild/bazelisk#how-does-bazelisk-know-which-bazel-version-to-run diff --git a/templates/bazelisk.yml b/templates/bazelisk/template.yml similarity index 100% rename from templates/bazelisk.yml rename to templates/bazelisk/template.yml diff --git a/templates/ruleset/.job.yml b/templates/ruleset/.job.yml index 718ff41..60479f5 100644 --- a/templates/ruleset/.job.yml +++ b/templates/ruleset/.job.yml @@ -20,7 +20,7 @@ spec: - error --- include: - - local: "/templates/bazelisk.yml" + - local: "/templates/bazelisk/template.yml" inputs: image: "$[[inputs.image]]" tag: "$[[inputs.tag]]" -- GitLab