{"id":35885500,"url":"https://gitlab.com/gitlab-ci-utils/gitlab-releaser","last_synced_at":"2026-01-08T20:02:19.867Z","repository":{"id":50686905,"uuid":"22151381","full_name":"gitlab-ci-utils/gitlab-releaser","owner":"gitlab-ci-utils","description":"Generate a shell script to create a release with the GitLab [release-cli](https://gitlab.com/gitlab-org/release-cli) application with the appropriate arguments.","archived":false,"fork":false,"pushed_at":null,"size":null,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":null,"default_branch":"main","last_synced_at":"2025-10-25T20:23:33.910Z","etag":null,"topics":["gitlab","gitlab-ci","node.js","npm"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":null,"metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2020-10-31T22:38:23.456Z","updated_at":"2025-10-25T15:24:42.383Z","dependencies_parsed_at":"2022-08-25T19:12:27.837Z","dependency_job_id":null,"html_url":"https://gitlab.com/gitlab-ci-utils/gitlab-releaser","commit_stats":null,"previous_names":[],"tags_count":17,"template":null,"template_full_name":null,"purl":"pkg:gitlab/gitlab-ci-utils/gitlab-releaser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-ci-utils%2Fgitlab-releaser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-ci-utils%2Fgitlab-releaser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-ci-utils%2Fgitlab-releaser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-ci-utils%2Fgitlab-releaser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners/gitlab-ci-utils","download_url":"https://gitlab.com/gitlab-ci-utils/gitlab-releaser/-/archive/main/gitlab-releaser-main.zip","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-ci-utils%2Fgitlab-releaser/sbom","scorecard":null,"host":{"name":"gitlab.com","url":"https://gitlab.com","kind":"gitlab","repositories_count":4521539,"owners_count":7348,"icon_url":"https://github.com/gitlab.png","version":null,"created_at":"2022-05-30T11:31:42.605Z","updated_at":"2024-07-18T11:24:13.055Z","status":"online","status_checked_at":"2026-01-08T02:00:07.634Z","response_time":284,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.382Z","robots_txt_url":"https://gitlab.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners"}},"keywords":["gitlab","gitlab-ci","node.js","npm"],"created_at":"2026-01-08T20:02:14.209Z","updated_at":"2026-01-08T20:02:19.852Z","avatar_url":null,"language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitLab Releaser\n\nGitLab Releaser takes a JSON file with release details, including defaults and\nrelease specific overrides, and generates a JSON file for a particular release\nthat can be passed to GitLab's\n[release-cli](https://gitlab.com/gitlab-org/release-cli/) application to create\nthe release. Special handling is provided to pull some values from the project\nCHANGELOG and for environment variables.\n\n## GitLab Releaser file\n\nGitLab Releaser can accept a GitLab Releaser file at\n`.gitlab/gitlab-releaser.json` which can contain default values applicable to\nall releases (`defaults`) and overrides for multiple specific releases denoted\nby release name (`releases`), for example:\n\n```json\n{\n  \"defaults\": {\n    \"assets\": {\n      \"links\": [\n        {\n          \"name\": \"npm\",\n          \"url\": \"https://www.npmjs.com/package/gitlab-releaser\",\n          \"type\": \"package\"\n        }\n      ]\n    }\n  },\n  \"releases\": {\n    \"1.0.0\": {\n      \"name\": \"v1.0.0 (2020-10-28)\",\n      \"description\": \"Another release\",\n      \"tag_name\": \"1.0.0\",\n      \"milestones\": [\"1.0.0\"]\n    },\n    \"0.5.0\": {\n      \"name\": \"v0.5.0 (2020-10-10)\",\n      \"description\": \"Initial release\",\n      \"tag_name\": \"0.5.0\",\n      \"milestones\": [\"0.5.0\"]\n    }\n  }\n}\n```\n\nThe `defaults` and each `releases` properties can contain any release\nproperties, and the `releases` properties override any `defaults` for that\nrelease. The resulting file is saved as `.gitlab/release.json`.\n\nThe complete list of release properties is shown below (all are optional\nexcept where otherwise noted):\n\n- `name`: Name of the release.\n- `description`: Description of the release.\n- `tag_name`: The tag to associate the release with.\n- `released_at`: The time of release.\n- `ref`: The commit ref to associate the release with.\n- `milestones`: An array of milestone names to associate the release with (for\n  example `['v1.0.0', 'v2.0.0']`).\n- `assets`: An object with the following properties:\n  - `links` (required if `assets` is specified): An array of asset links with\n    the following properties:\n    - `name` (required): The displayed name of the link.\n    - `url` (required): The URL of the link.\n    - `type`: The type of link, one of:\n      - `package`: A link to a package.\n      - `image`: A link to an image.\n      - `archive`: A link to an archive.\n      - `other`: A link to another type of asset (default).\n    - `direct_asset_path`: The path to the asset file.\n\nA release name must be specified via the CLI to pull the appropriate release\ninformation. For example, `--release 1.0.0` would result in the following\n`.gitlab/release.json` file. Note some property have slightly different names\nto match the `release-cli` file schema (for example `tag-name`, `assets-link`).\nThe release property names in the preceding section have been found to be more\nintuitive, even though different.\n\n```json\n{\n  \"name\": \"v1.0.0 (2020-10-28)\",\n  \"description\": \"Another release\",\n  \"tag-name\": \"1.0.0\",\n  \"assets-link\": [\n    \"{\\\"name\\\":\\\"npm\\\",\\\"url\\\":\\\"https://www.npmjs.com/package/gitlab-releaser\\\",\\\"type\\\":\\\"package\\\"}\"\n  ],\n  \"milestones\": [\"1.0.0\"]\n}\n```\n\nThe full GitLab Releaser file JSON schema is available in\n[this example](https://gitlab.com/gitlab-ci-utils/gitlab-releaser/-/raw/master/schemas/gitlab-releaser.schema.json).\nAn example `release-cli` file with all properties is available in\n[this example](https://gitlab.com/gitlab-ci-utils/gitlab-releaser/-/raw/master/schemas/release-cli.schema.json).\nNote that although `release-cli` accept a YAML file, GitLab Releaser generates\nthe equivalent JSON file (YAML being a superset of JSON, so a JSON file is\nvalid YAML).\n\n### Pulling data from changelog\n\nThe release `name` and `description` can optionally be pulled dynamically from\nthe CHANGELOG. This is done if the value specified in the Release or GitLab\nReleaser file is \"`$$CHANGELOG`,\" for example:\n\n```json\n{\n  \"name\": \"$$CHANGELOG\",\n  \"description\": \"$$CHANGELOG\",\n  \"tag_name\": \"1.0.0\"\n}\n```\n\nThe [`releaselog`](https://www.npmjs.com/package/releaselog) package is used to\nlocate the CHANGELOG file, and by default looks in the current working\ndirectory and has logic to locate the CHANGELOG or determine which to use if\nmultiple are found. A different CHANGELOG directory, or a specific file path,\ncan alternatively be specified via the CLI. The\n[`releaselog`](https://www.npmjs.com/package/releaselog) package is also used\nto pull data from the CHANGELOG and has details on CHANGELOG formatting\nrequirements. The data is retrieved by the tag specified via the CLI, if\nspecified, otherwise the value of `CI_COMMIT_TAG` is used. Either a release\nname or the default value must be specified via the CLI if the release uses\nCHANGELOG data.\n\nIf either `name` or `description` specifies pulling data from the CHANGELOG and\neither the CHANGELOG can't be found or the release data can't be found in the\nCHANGELOG the job reports the error and fail.\n\nAlso, if the `description` retrieved from the CHANGELOG is empty the job\nreports the error and fail. This is almost always a CHANGELOG formatting or\ncontent issue, but there is a CLI option to allow an empty description if\nrequired (`--allow-empty-changelog-desc`).\n\n### Environment variables\n\nGitLab Releaser tries to expand any environment variables in release properties\nthat match either the format `${VARIABLE}` or `$VARIABLE`. If the given\nvariable has a value it is expanded, for example if the `tag_name` property is\nset to `v${CI_COMMIT_TAG}`, and the `CI_COMMIT_TAG` environment variable has\nthe value `1.0.0`, the resulting property is `v1.0.0`. Variables are expanded\nbefore CHANGELOG data is pulled, so variables in the CHANGELOG are not\nexpanded.\n\nIf the variable doesn't have a value, the job reports the error and fails.\nThere is a CLI option to allow empty variables if desired\n(`--allow-empty-variables`), and in this case the variables aren't expanded.\n\n## Usage\n\n### Command line usage\n\nThe `gitlab-releaser` command line interface is detailed below:\n\n```sh\nUsage: gitlab-releaser [options]\n\nOptions:\n  -V, --version                     output the version number\n  -r, --release \u003crelease\u003e           the reference used to retrieve release data\n                                    (default: \"$CI_COMMIT_TAG\")\n  -c, --changelog \u003cchangelog\u003e       the path to the CHANGELOG to check if the\n                                    release pulls data from the CHANGELOG\n                                    (default: \".\")\n  -a, --allow-empty-changelog-desc  allow an empty description when pulled from\n                                    the CHANGELOG (default: false)\n  -v, --allow-empty-variables       allow environment variables that are empty\n                                    and are not expanded (default: false)\n  -h, --help                        display help for command\n```\n\n### GitLab CI usage\n\nThe following is an example `.gitlab-ci.yml` file illustrating preparing and\ncreating a release on every tag pipeline.\n\n```yaml\nprepare_release:\n  image: node:lts-alpine\n  needs: []\n  before_script:\n    - npm install -g gitlab-releaser\n  script:\n    - gitlab-releaser\n  rules:\n    - if: $CI_COMMIT_TAG\n  artifacts:\n    paths:\n      - '.gitlab/release.json'\n\ncreate_release:\n  image: registry.gitlab.com/gitlab-org/release-cli:latest\n  needs:\n    - prepare_release\n  script:\n    - release-cli create-from-file -file .gitlab/release.json\n  rules:\n    - if: $CI_COMMIT_TAG\n```\n\nThe process is split into two jobs to avoid having to create a container image\nthat can run this Node.js application to prepare the release and has GitLab's\nrelease-cli application to create the release.\n\nThe `prepare_release` job uses a Node.js container image and installs and runs\n`gitlab-releaser` to generate the JSON file for the release, saved as\n`.gitlab/release.json`. The `create_release` job then uses GitLab's\n`release-cli` container image (`registry.gitlab.com/gitlab-org/release-cli`)\nto run `release-cli`, pulling values from the file `.gitlab/release.json`.\n\n### GitLab CI usage without release files\n\nThe example below shows how to setup a GitLab `prepare_release` job template\nwith a default release configuration defined in CI job (in the environment\nvariable `$RELEASE`, which contains the minified configuration from a\n`gitlab-releaser.json` file), which is only used if the project doesn't have\nit's own `gitlab-releaser.json` file.\n\n```yaml\n# gitlab-releaser.gitlab-ci.yml\nprepare_release:\n  image: node:lts-alpine\n  needs: []\n  variables:\n    # Set default to create a release that pulls the name and description from\n    # the project CHANGELOG. Use expand false to not try to expand the $.\n    RELEASE:\n      value: '{\"defaults\":{\"name\":\"$$CHANGELOG\",\"description\":\"$$CHANGELOG\"}}'\n      expand: false\n\n  before_script:\n    - npm install -g gitlab-releaser\n    # If a GitLab Releaser file does not exists, create a file with the release from variable.\n    - |\n      if [ ! -f .gitlab/gitlab-releaser.json ]; then\n        mkdir -p .gitlab \u0026\u0026 echo $RELEASE \u003e .gitlab/gitlab-releaser.json\n      fi\n  script:\n    - gitlab-releaser\n  rules:\n    - if: $CI_COMMIT_TAG\n  artifacts:\n    paths:\n      - '.gitlab/release.json'\n```\n\nThe default release configuration can then be overridden by including this\ntemplate, and simply overriding the `$RELEASE` variable with the minified\nconfiguration from a `gitlab-releaser.json` file.\n\n```yaml\ninclude:\n  # Include from the appropriate location\n  - local: 'gitlab-releaser.gitlab-ci.yml'\n\nprepare_release:\n  variables:\n    RELEASE:\n      value: '{\"defaults\":{\"name\":\"${CI_COMMIT_TAG}\",\"description\":\"$$CHANGELOG\"}}'\n      expand: false\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fgitlab-ci-utils%2Fgitlab-releaser","html_url":"https://awesome.ecosyste.ms/projects/gitlab.com%2Fgitlab-ci-utils%2Fgitlab-releaser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fgitlab-ci-utils%2Fgitlab-releaser/lists"}