diff --git a/README.md b/README.md index 16216cd028e0448cd58fc3763a8c86579594e63e..46fea9ae10e55db139cff5470266e37be43fd0ef 100644 --- a/README.md +++ b/README.md @@ -46,16 +46,16 @@ variables: The semantic-release template uses some global configuration used throughout all jobs. -| Input / Variable | Description | Default value | -| --------------------- | --------------------------------------------- | ----------------- | -| `image` / `SEMREL_IMAGE` | The Docker image used to run semantic-release | `registry.hub.docker.com/library/node:latest` | -| `version` / `SEMREL_VERSION` | The [semantic-release](https://www.npmjs.com/package/semantic-release) version to use | `latest` | -| `exec-version` / `SEMREL_EXEC_VERSION` | The [@semantic-release/exec](https://www.npmjs.com/package/@semantic-release/exec) version to use | `latest` | -| :lock: `GITLAB_TOKEN` | A GitLab [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html) with `api`, `read_repository` and `write repository` scopes. :warning: This variable is **mandatory** and [defined by `semantic-release`](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#push-access-to-the-remote-repository) itself. | _none_ | -| :lock: `GIT_AUTHOR_EMAIL` | A Git author email address associated with the `GITLAB_TOKEN` [bot user](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#bot-users-for-projects). This is [defined by `semantic-release`](https://semantic-release.gitbook.io/semantic-release/usage/configuration#git-environment-variables) itself, and **required if** the [verify-user push rules](https://docs.gitlab.com/ee/user/project/repository/push_rules.html#verify-users) enabled for the project | _none_ | -| :lock: `GIT_COMMITTER_EMAIL` | A Git committer email address associated with the `GITLAB_TOKEN` [bot user](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#bot-users-for-projects). This is [defined by `semantic-release`](https://semantic-release.gitbook.io/semantic-release/usage/configuration#git-environment-variables) itself, and **required if** the [verify-user push rules](https://docs.gitlab.com/ee/user/project/repository/push_rules.html#verify-users) enabled for the project | _none_ | -| `config-dir` / `SEMREL_CONFIG_DIR` | directory containing your [semantic-release configuration](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) | `.` | -| `required-plugins-file` / `SEMREL_REQUIRED_PLUGINS_FILE` | An optional file for additional npm packages to install | `semrel-required-plugins.txt` | +| Input / Variable | Description | Default value | +| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| `image` / `SEMREL_IMAGE` | The Docker image used to run semantic-release | `registry.hub.docker.com/library/node:latest` | +| `version` / `SEMREL_VERSION` | The [semantic-release](https://www.npmjs.com/package/semantic-release) version to use | `latest` | +| `exec-version` / `SEMREL_EXEC_VERSION` | The [@semantic-release/exec](https://www.npmjs.com/package/@semantic-release/exec) version to use | `latest` | +| :lock: `GITLAB_TOKEN` | A GitLab [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html) with `api`, `read_repository` and `write repository` scopes. :warning: This variable is **mandatory** and [defined by `semantic-release`](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#push-access-to-the-remote-repository) itself. | _none_ | +| :lock: `GIT_AUTHOR_EMAIL` | A Git author email address associated with the `GITLAB_TOKEN` [bot user](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#bot-users-for-projects). This is [defined by `semantic-release`](https://semantic-release.gitbook.io/semantic-release/usage/configuration#git-environment-variables) itself, and **required if** the [verify-user push rules](https://docs.gitlab.com/ee/user/project/repository/push_rules.html#verify-users) enabled for the project | _none_ | +| :lock: `GIT_COMMITTER_EMAIL` | A Git committer email address associated with the `GITLAB_TOKEN` [bot user](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#bot-users-for-projects). This is [defined by `semantic-release`](https://semantic-release.gitbook.io/semantic-release/usage/configuration#git-environment-variables) itself, and **required if** the [verify-user push rules](https://docs.gitlab.com/ee/user/project/repository/push_rules.html#verify-users) enabled for the project | _none_ | +| `config-dir` / `SEMREL_CONFIG_DIR` | directory containing your [semantic-release configuration](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) | `.` | +| `required-plugins-file` / `SEMREL_REQUIRED_PLUGINS_FILE` | An optional file for additional npm packages to install | `semrel-required-plugins.txt` | Jobs will extract required plugin packages from discovered configuration. If your configuration needs additional packages, add them, one per line, to `SEMREL_REQUIRED_PLUGINS_FILE` file. Each line must be a valid `npm install` package argument. @@ -85,17 +85,18 @@ If no configuration is found, the template will generate one with the following As specified in the previous chapter, these variables are only used to generated a `.releaserc` when no configuration is found in the repository. -| Input / Variable | Description | Default value | -| ------------------------------| ------------------------------------------------------ | ------------- | -| `changelog-enabled` / `SEMREL_CHANGELOG_ENABLED` | Add the [@semantic-release/changelog](https://github.com/semantic-release/changelog) plugin which will commit a changelog file in the repository if set to `true`. | _none_ | -| `changelog-file` / `SEMREL_CHANGELOG_FILE` | [changelogFile @semantic-release/changelog option](https://github.com/semantic-release/changelog#options). | _none_ (use the plugin default value which is `CHANGELOG.md`). | -| `changelog-title` / `SEMREL_CHANGELOG_TITLE` | [changelogTitle @semantic-release/changelog option](https://github.com/semantic-release/changelog#options). You might want to use markdown format (for example `# MyApp Changelog`). | _none_ | -| `dry-run` / `SEMREL_DRY_RUN` | Activate the [dryRun semantic-release option](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#dryrun) if present. | _none_ | -| `auto-release-enabled` / `SEMREL_AUTO_RELEASE_ENABLED` | When set to `true` the job start automatically. When not set (default), the job is manual. | _none_ | -| `tag-format` / `SEMREL_TAG_FORMAT` | [tagFormat semantic-release option](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#tagformat). :warning: don't forget to double the `$` character so it is not interpreted by GitLab. | `$${version}` | -| `hooks-dir` / `SEMREL_HOOKS_DIR` | [Hook scripts](#hook_scripts) folder. | `.` | -| `commit-message` / `SEMREL_COMMIT_MESSAGE` | Add a custom commit message based on [semantic-release/git option](https://github.com/semantic-release/git#message). | _none_ (uses semantic-release default commit message) | -| `release-disabled` / `SEMREL_RELEASE_DISABLED` | Disable this job. | _none_ | +| Input / Variable | Description | Default value | +| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `changelog-enabled` / `SEMREL_CHANGELOG_ENABLED` | Add the [@semantic-release/changelog](https://github.com/semantic-release/changelog) plugin which will commit a changelog file in the repository if set to `true`. | _none_ | +| `changelog-file` / `SEMREL_CHANGELOG_FILE` | [changelogFile @semantic-release/changelog option](https://github.com/semantic-release/changelog#options). | _none_ (use the plugin default value which is `CHANGELOG.md`). | +| `changelog-title` / `SEMREL_CHANGELOG_TITLE` | [changelogTitle @semantic-release/changelog option](https://github.com/semantic-release/changelog#options). You might want to use markdown format (for example `# MyApp Changelog`). | _none_ | +| `dry-run` / `SEMREL_DRY_RUN` | Activate the [dryRun semantic-release option](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#dryrun) if present. | _none_ | +| `auto-release-enabled` / `SEMREL_AUTO_RELEASE_ENABLED` | When set to `true` the job start automatically. When not set (default), the job is manual. | _none_ | +| `branches-ref` / `SEMREL_BRANCHES_REF` | Regular expression pattern matching branches from which releases should happen (should match your [semantic-release configuration](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches)) | `$PROD_REF` ([global _to be continuous_ variable](https://to-be-continuous.gitlab.io/doc/usage/#production-and-integration-branches)) | +| `tag-format` / `SEMREL_TAG_FORMAT` | [tagFormat semantic-release option](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#tagformat). :warning: don't forget to double the `$` character so it is not interpreted by GitLab. | `$${version}` | +| `hooks-dir` / `SEMREL_HOOKS_DIR` | [Hook scripts](#hook_scripts) folder. | `.` | +| `commit-message` / `SEMREL_COMMIT_MESSAGE` | Add a custom commit message based on [semantic-release/git option](https://github.com/semantic-release/git#message). | _none_ (uses semantic-release default commit message) | +| `release-disabled` / `SEMREL_RELEASE_DISABLED` | Disable this job. | _none_ | #### Hook scripts @@ -163,8 +164,8 @@ For an introduction on commit signing, see [GitLab documentation](https://docs.g To make semantic-release sign its commits, use the following variable. -| Input / Variable | Description | Default value | -| ---------------------| ------------------------------------------------------------------------ | ------------- | +| Input / Variable | Description | Default value | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | :lock: `SEMREL_GPG_SIGNKEY` | Path to the GPG signkey exported with `gpg --armor --export-secret-key`<br/>:warning: Declare as a masked [project variable of File type](https://docs.gitlab.com/ee/ci/variables/#cicd-variable-types). | _none_ | ### `semantic-release-info` job @@ -179,7 +180,8 @@ This job (disabled by default) runs `semantic-release` with `dry-run` mode in `. This job can be enabled by defining the `SEMREL_INFO_ON` variable: -* `prod` to enable on production branch only (`main` or `master` by default) +* `prod` to enable on production branch only (`main` or `master` by default with `PROD_REF` environment variable) +* `branches-ref` to enable on branches associated with `branches-ref` component configuration or `SEMREL_BRANCHES_REF` environment variable (`main` or `master` by default as it fallbacks on `PROD_REF` environment variable). * `protected` to enable on protected references * `all` to enable on all Git references. :warning: Beware that this job requires the `GITLAB_TOKEN` variable so you must unprotect it (this will make privilege escalation possible from developer to maintainer). @@ -210,13 +212,13 @@ This variant allows delegating your secrets management to a [Vault](https://www. In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters: -| Input / Variable | Description | Default value | -| ----------------- | -------------------------------------- | ----------------- | -| `TBC_VAULT_IMAGE` | The [Vault Secrets Provider](https://gitlab.com/to-be-continuous/tools/vault-secrets-provider) image to use (can be overridden) | `registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest` | -| `vault-base-url` / `VAULT_BASE_URL` | The Vault server base API url | _none_ | -| `vault-oidc-aud` / `VAULT_OIDC_AUD` | The `aud` claim for the JWT | `$CI_SERVER_URL` | -| :lock: `VAULT_ROLE_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) RoleID | **must be defined** | -| :lock: `VAULT_SECRET_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) SecretID | **must be defined** | +| Input / Variable | Description | Default value | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `TBC_VAULT_IMAGE` | The [Vault Secrets Provider](https://gitlab.com/to-be-continuous/tools/vault-secrets-provider) image to use (can be overridden) | `registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest` | +| `vault-base-url` / `VAULT_BASE_URL` | The Vault server base API url | _none_ | +| `vault-oidc-aud` / `VAULT_OIDC_AUD` | The `aud` claim for the JWT | `$CI_SERVER_URL` | +| :lock: `VAULT_ROLE_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) RoleID | **must be defined** | +| :lock: `VAULT_SECRET_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) SecretID | **must be defined** | #### Usage @@ -228,9 +230,9 @@ Then you may retrieve any of your secret(s) from Vault using the following synta With: -| Parameter | Description | -| -------------------------------- | -------------------------------------- | -| `secret_path` (_path parameter_) | this is your secret location in the Vault server | +| Parameter | Description | +| -------------------------------- | --------------------------------------------------------------------- | +| `secret_path` (_path parameter_) | this is your secret location in the Vault server | | `field` (_query parameter_) | parameter to access a single basic field from the secret JSON payload | #### Example diff --git a/kicker.json b/kicker.json index 0828c8619b452f0a2b5668d700e7c1ab8168ddcb..b5f358326ab6cc5388ca8f765fd8f28ca120ba40 100644 --- a/kicker.json +++ b/kicker.json @@ -83,6 +83,12 @@ "description": "When set the job start automatically. When not set (default), the job is manual.", "type": "boolean" }, + { + "name": "SEMREL_BRANCHES_REF", + "description": "Regular expression pattern matching branches from which releases should happen (should match your [semantic-release configuration](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches))", + "default": "$PROD_REF", + "advanced": true + }, { "name": "SEMREL_HOOKS_DIR", "description": "Hook scripts folder.", @@ -111,7 +117,7 @@ "name": "SEMREL_INFO_ON", "description": "Define on which branch(es) the job shall be run", "type": "enum", - "values": ["", "prod", "protected", "all"], + "values": ["", "prod", "branches-ref", "protected", "all"], "mandatory": true } ] diff --git a/templates/gitlab-ci-semrel.yml b/templates/gitlab-ci-semrel.yml index 250daeff426d5a0985cfa3547df3880d37dd7398..2e235cc802b2553168def1adea42c83687e646ab 100644 --- a/templates/gitlab-ci-semrel.yml +++ b/templates/gitlab-ci-semrel.yml @@ -22,6 +22,9 @@ spec: version: description: The [semantic-release](https://www.npmjs.com/package/semantic-release) version to use default: latest + branches-ref: + description: Regular expression pattern matching branches from which releases should happen (should match your [semantic-release configuration](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches)) + default: $PROD_REF exec-version: description: The [@semantic-release/exec](https://www.npmjs.com/package/@semantic-release/exec) version to use default: latest @@ -67,6 +70,7 @@ spec: options: - '' - prod + - branches-ref - protected - all default: '' @@ -128,6 +132,7 @@ variables: # default production ref name (pattern) PROD_REF: /^(master|main)$/ + SEMREL_BRANCHES_REF: $[[ inputs.branches-ref ]] stages: - build @@ -704,6 +709,7 @@ semantic-release-info: - if: $CI_COMMIT_TAG when: never - if: '$SEMREL_INFO_ON == "prod" && $CI_COMMIT_REF_NAME =~ $PROD_REF' + - if: '$SEMREL_INFO_ON == "branches-ref" && $CI_COMMIT_REF_NAME =~ $SEMREL_BRANCHES_REF' - if: '$SEMREL_INFO_ON == "protected" && $CI_COMMIT_REF_PROTECTED == "true"' - if: '$SEMREL_INFO_ON == "all"' @@ -720,9 +726,11 @@ semantic-release: when: never - if: $CI_COMMIT_TAG when: never - # on production branch(es): auto if SEMREL_AUTO_RELEASE_ENABLED - - if: '$SEMREL_AUTO_RELEASE_ENABLED == "true" && $CI_COMMIT_REF_NAME =~ $PROD_REF' - # on production branch(es): manual by default - - if: '$CI_COMMIT_REF_NAME =~ $PROD_REF' - when: manual + # exclude if branch doesn't match $SEMREL_BRANCHES_REF + - if: '$CI_COMMIT_REF_NAME !~ $SEMREL_BRANCHES_REF' + when: never + # if $SEMREL_AUTO_RELEASE_ENABLED: auto + - if: '$SEMREL_AUTO_RELEASE_ENABLED == "true"' + # else manual + - when: manual allow_failure: true