gitlab-releaser
v8.0.4
Published
Generate arguments for GitLab release-cli command
Downloads
100
Maintainers
Readme
GitLab Releaser
GitLab Releaser takes a JSON file with release details, including defaults and release specific overrides, and generates a JSON file for a particular release that can be passed to GitLab's release-cli application to create the release. Special handling is provided to pull some values from the project CHANGELOG and for environment variables.
GitLab Releaser file
GitLab Releaser can accept a GitLab Releaser file at
.gitlab/gitlab-releaser.json
which can contain default values applicable to
all releases (defaults
) and overrides for multiple specific releases denoted
by release name (releases
), for example:
{
"defaults": {
"assets": {
"links": [
{
"name": "npm",
"url": "https://www.npmjs.com/package/gitlab-releaser",
"type": "package"
}
]
}
},
"releases": {
"1.0.0": {
"name": "v1.0.0 (2020-10-28)",
"description": "Another release",
"tag_name": "1.0.0",
"milestones": ["1.0.0"]
},
"0.5.0": {
"name": "v0.5.0 (2020-10-10)",
"description": "Initial release",
"tag_name": "0.5.0",
"milestones": ["0.5.0"]
}
}
}
The defaults
and each releases
properties can contain any release
properties, and the releases
properties override any defaults
for that
release. The resulting file is saved as .gitlab/release.json
.
The complete list of release properties is shown below (all are optional except where otherwise noted):
name
: Name of the release.description
: Description of the release.tag_name
: The tag to associate the release with.released_at
: The time of release.ref
: The commit ref to associate the release with.milestones
: An array of milestone names to associate the release with (for example['v1.0.0', 'v2.0.0']
).assets
: An object with the following properties:links
(required ifassets
is specified): An array of asset links with the following properties:name
(required): The displayed name of the link.url
(required): The URL of the link.type
: The type of link, one of:package
: A link to a package.image
: A link to an image.archive
: A link to an archive.other
: A link to another type of asset (default).
direct_asset_path
: The path to the asset file.
A release name must be specified via the CLI to pull the appropriate release
information. For example, --release 1.0.0
would result in the following
.gitlab/release.json
file. Note some property have slightly different names
to match the release-cli
file schema (for example tag-name
, assets-link
).
The release property names in the preceding section have been found to be more
intuitive, even though different.
{
"name": "v1.0.0 (2020-10-28)",
"description": "Another release",
"tag-name": "1.0.0",
"assets-link": [
"{\"name\":\"npm\",\"url\":\"https://www.npmjs.com/package/gitlab-releaser\",\"type\":\"package\"}"
],
"milestones": ["1.0.0"]
}
The full GitLab Releaser file JSON schema is available
here.
An example release-cli
file with all properties is available
here.
Note that although release-cli
accept a YAML file, GitLab Releaser generates
the equivalent JSON file (YAML being a superset of JSON, so a JSON file is
valid YAML).
Pulling data from changelog
The release name
and description
can optionally be pulled dynamically from
the CHANGELOG. This is done if the value specified in the Release or GitLab
Releaser file is "$$CHANGELOG
," for example:
{
"name": "$$CHANGELOG",
"description": "$$CHANGELOG",
"tag_name": "1.0.0"
}
The releaselog
package is used to
locate the CHANGELOG file, and by default looks in the current working
directory and has logic to locate the CHANGELOG or determine which to use if
multiple are found. A different CHANGELOG directory, or a specific file path,
can alternatively be specified via the CLI. The
releaselog
package is also used
to pull data from the CHANGELOG and has details on CHANGELOG formatting
requirements. The data is retrieved by the tag specified via the CLI, if
specified, otherwise the value of CI_COMMIT_TAG
is used. Either a release
name or the default value must be specified via the CLI if the release uses
CHANGELOG data.
If either name
or description
specifies pulling data from the CHANGELOG and
either the CHANGELOG can't be found or the release data can't be found in the
CHANGELOG the job reports the error and fail.
Also, if the description
retrieved from the CHANGELOG is empty the job
reports the error and fail. This is almost always a CHANGELOG formatting or
content issue, but there is a CLI option to allow an empty description if
required (--allow-empty-changelog-desc
).
Environment variables
GitLab Releaser tries to expand any environment variables in release properties
that match either the format ${VARIABLE}
or $VARIABLE
. If the given
variable has a value it is expanded, for example if the tag_name
property is
set to v${CI_COMMIT_TAG}
, and the CI_COMMIT_TAG
environment variable has
the value 1.0.0
, the resulting property is v1.0.0
. Variables are expanded
before CHANGELOG data is pulled, so variables in the CHANGELOG are not
expanded.
If the variable doesn't have a value, the job reports the error and fails.
There is a CLI option to allow empty variables if desired
(--allow-empty-variables
), and in this case the variables aren't expanded.
Usage
Command line usage
The gitlab-releaser
command line interface is detailed below:
Usage: gitlab-releaser [options]
Options:
-V, --version output the version number
-r, --release <release> the reference used to retrieve release data
(default: "$CI_COMMIT_TAG")
-c, --changelog <changelog> the path to the CHANGELOG to check if the
release pulls data from the CHANGELOG
(default: ".")
-a, --allow-empty-changelog-desc allow an empty description when pulled from
the CHANGELOG (default: false)
-v, --allow-empty-variables allow environment variables that are empty
and are not expanded (default: false)
-h, --help display help for command
GitLab CI usage
The following is an example .gitlab-ci.yml
file illustrating preparing and
creating a release on every tag pipeline.
prepare_release:
image: node:lts-alpine
needs: []
before_script:
- npm install -g gitlab-releaser
script:
- gitlab-releaser
rules:
- if: $CI_COMMIT_TAG
artifacts:
paths:
- '.gitlab/release.json'
create_release:
image: registry.gitlab.com/gitlab-org/release-cli:latest
needs:
- prepare_release
script:
- release-cli create-from-file -file .gitlab/release.json
rules:
- if: $CI_COMMIT_TAG
The process is split into two jobs to avoid having to create a container image that can run this Node.js application to prepare the release and has GitLab's release-cli application to create the release.
The prepare_release
job uses a Node.js container image and installs and runs
gitlab-releaser
to generate the JSON file for the release, saved as
.gitlab/release.json
. The create_release
job then uses GitLab's
release-cli
container image (registry.gitlab.com/gitlab-org/release-cli
)
to run release-cli
, pulling values from the file .gitlab/release.json
.
GitLab CI usage without release files
The example below shows how to setup a GitLab prepare_release
job template
with a default release configuration defined in CI job (in the environment
variable $RELEASE
, which contains the minified configuration from a
gitlab-releaser.json
file), which is only used if the project doesn't have
it's own gitlab-releaser.json
file.
# gitlab-releaser.gitlab-ci.yml
prepare_release:
image: node:lts-alpine
needs: []
variables:
# Set default to create a release that pulls the name and description from
# the project CHANGELOG. Use expand false to not try to expand the $.
RELEASE:
value: '{"defaults":{"name":"$$CHANGELOG","description":"$$CHANGELOG"}}'
expand: false
before_script:
- npm install -g gitlab-releaser
# If a GitLab Releaser file does not exists, create a file with the release from variable.
- |
if [ ! -f .gitlab/gitlab-releaser.json ]; then
mkdir -p .gitlab && echo $RELEASE > .gitlab/gitlab-releaser.json
fi
script:
- gitlab-releaser
rules:
- if: $CI_COMMIT_TAG
artifacts:
paths:
- '.gitlab/release.json'
The default release configuration can then be overridden by including this
template, and simply overriding the $RELEASE
variable with the minified
configuration from a gitlab-releaser.json
file.
include:
# Include from the appropriate location
- local: 'gitlab-releaser.gitlab-ci.yml'
prepare_release:
variables:
RELEASE:
value: '{"defaults":{"name":"${CI_COMMIT_TAG}","description":"$$CHANGELOG"}}'
expand: false