diff --git a/.releaserc.yaml b/.releaserc.yaml index efc2cc64c556ea042a34e1cb2bb0ab027c8b4dd6..e38915a96b2197efe6a4c4d8aa9033ecf9a5620c 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}" @@ -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}" @@ -48,13 +48,13 @@ plugins: assets: - "MODULE.bazel" - "CHANGELOG.md" - - "templates/bazelisk.yml" + - "templates/bazelisk/template.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/.reuse/dep5 b/.reuse/dep5 index 14408a24372750ff8d78d93582ac6fb0365f3362..cdabe091ebd834134c1d7edff4a6e61743ba5ec1 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 2d6ba6954b60bbef4c41a0e09a8a5bda4754347a..9d3e6148b700dca6406641376e0bf9aec4a0db2a 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 0000000000000000000000000000000000000000..1cc1ea60189bd8b96bed1a788d99c2ddf6e6e64c --- /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/config/README.md b/templates/config/README.md new file mode 100644 index 0000000000000000000000000000000000000000..b6b328fba954055f2c907da144732a1e783d606a --- /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 0000000000000000000000000000000000000000..8227fc0bc59a7acae08910d2213c9b5c68c5de43 --- /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/.job.yml b/templates/ruleset/.job.yml index 718ff411d430e9b4cb8917b8afd12731b0088b2d..60479f5398f897838fd9e6222bc4b6351d416799 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]]" diff --git a/templates/ruleset/template.yml b/templates/ruleset/template.yml index f7937a3d4a8c7e0c45ddb6a04f23974f41eea7f5..a1bc5dcf51c0dc51a43b5b11ced3ce12efc48f49 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,11 @@ 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]]" + needs: + - config + - version + - os diff --git a/templates/semantic-release/README.md b/templates/semantic-release/README.md new file mode 100644 index 0000000000000000000000000000000000000000..8e4f8f04952075be352b87208e33300919349329 --- /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 89% rename from templates/ruleset/semantic-release.yml rename to templates/semantic-release/template.yml index 040259efc8769845d973c7fed6df2d49272cf45b..b0bbbfa891e9b51061ec04fca11a812cd082851c 100644 --- a/templates/ruleset/semantic-release.yml +++ b/templates/semantic-release/template.yml @@ -6,11 +6,14 @@ spec: tag: default: latest description: "Open container image (OCI) tag for the image." - needs: + extends: type: array default: - - config - - version + - .job + description: "Jobs to extend." + needs: + type: array + default: [] description: "Jobs to run before the `semantic-release` job." --- include: @@ -21,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]] diff --git a/templates/version/README.md b/templates/version/README.md new file mode 100644 index 0000000000000000000000000000000000000000..ea02501b50931735e2ce2e834857914135383641 --- /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