Add an option to output the version that would be published

[BenoitAverty]

Feature request

New feature motivation

I am currently implementing automatic releases for my project, which is a web application. The project currently satisfies my needs as I can disable the npm plugins and replace it with gitlab plugins.

The problem is that I need to put the version of my project into the built application (via Webpack's DefinePlugin), but the version field of my package.json is always set to 0.0.0.

I would like to be able to use semantic-release to print the version that would be published and use it in webpack DefinePlugin.

Currently, the only way to do that would be to parse the output of a dry-run, but it is complicated and not stable.

New feature description

I see two ways this could happen :

• The simple one is to provide a cli option to instruct semantic release to just print the version. For example semantic-release --print-next-version
• Allow a more extensive programmatic usage of semantic-release, with a JS api that would (among other things) allow to retrieve the next version.

I could open a PR for the first solution if you'd like. The second one is a bigger task (probably several tasks)

[gr2m]

I think you can run a custom script in the prepublishOnly script, see https://semantic-release.gitbooks.io/semantic-release/docs/support/FAQ.html#how-can-i-use-a-npm-build-script-that-requires-the-packagejsons-version-

At this point the version in package.json is set. Your custom script can read it and write it into your build files

[BenoitAverty]

I would but unfortunately I don't publish with npm. My build script is executed way before the semantic release.

[gr2m]

you can use semantic-release without publishing to npm, you can create a prepare plugin at which point the new version will be available to your script, see for example https://github.com/GabrielDuarteM/semantic-release-chrome/blob/dd75ea42bdc6a21a138ae76fc73dd13b2570d43d/src/prepare.ts#L22

see also https://semantic-release.gitbooks.io/semantic-release/docs/extending/plugins-list.html

[pvdlg]

You can also use the @semantic-release/exec to run a script at any step you'd like that can be passed the new version number. Something like that:

{
  "release": {
    "prepare": [
      "@semantic-release/npm",
      {
        "path": "@semantic-release/exec",
        "cmd": "my-script ${nextRelease.version}",
      },
    ],
  }
}

With this config the npm plugin is going to update your package.json first, then my-script will be called with the new version as first argument.

[BenoitAverty]

The problem with all these solutions is that I need to have two configurations : One that outputs the version or sets it somewhere, and one for the actual release in gitlab (tag, etc.) which doesn't seem to be possible easily.

For now I think i'll parse the output of a dry-run, but this is really brittle if the output changes.

[pvdlg]

The problem with all these solutions is that I need to have two configurations : One that outputs the version or sets it somewhere, and one for the actual release in gitlab (tag, etc.) which doesn't seem to be possible easily.

Do you mean two semantic-release config? Can you clarify why would you need two configs?

[BenoitAverty]

I will try to be more detailed about my workflow.

I have a Gitlab-CI pipeline that does this jobs in order :

1) Build my application (npm run build && docker build)
2) Deploy a review environment in kubernetes
3) Run e2e tests against this review environment
4) If the tests are OK && the branch is master, release with semantic-release 

The problem is that the customer wants to see the version number inside the application (and maybe the changelog later). Wich means I need the version number during step 1, but I don't want to release yet (the tests could still fail).

The two semantic-release configurations would allow me to use @semantic-release/exec

Config one : only exec during prepare that does npm version ${nextRelease.version}
Config two : the real configuration that does changelog, version bump, gitlab release, etc.

But the preferred method would just be to have a command that outputs the next version. I would use that during step one.

I hope it's more clear, don't hesitate to ask for more details.

[pvdlg]

Thanks for the clarification.

semantic-release is build around the following ideas:

• A release consist in running test, defining the version then releasing
• A given release happens only once

It seems your steps 1 and 2 are actually tests, but handled like a release. In semantic-release, it has to be either a test step or a release step. If it's a test, there is no version determined, if it's a release there is one.

If you need the version number for step 1 and 2 then it's a release. Your workflow could be viewed as doing two different release:

• One "pre-release" or "release candidate" that will go through integration testing
• One final release if the integration test are successful

We usually handle this case via npm dist-tag. Until #563 get implemented the support of dist-tag is fairly simple unfortunately as we support one dist-tag config in the package.json and pre-releases are not supported.

Once #563 is implemented you could do the following workflow:

• Set up the branches master and rc
• Configure master to release on the @latest dist-tag
• Configure rc to release on the @rc dist-tag
• Configure semantic-release to do the whole release (build, version bump, changelog, gitlab release, deploy on kubernetes, run e2e tests, etc...)
• Push your new code (i.e. merge your PRs) into the rc branch
• Once a release released on @rc passes all the integration tests, merge the rc branch into master, semantic-release will make the @rc release available on @latest

This way:

• Every time you run your CI and there is new relevant commits you make a release
• Each release candidate is actually a real release (with git tag, gitlab release, changelog etc...)
• All your releases go through the integration test process
• Only the satisfying releases are made available on @latest and used by the final users

With the current implementation you can do something that involve some manual steps:

• Configure the dist-tag @rc in your package.json's publishConfig.tag property
• Configure semantic-release to do the whole release (build, version bump, changelog, gitlab release, deploy on kubernetes, run e2e tests, etc...)
• Push your new code (i.e. merge your PRs) into the master branch as your currently do
• When a @rc release passes the test and is considered ready to be made available to users, make it available on @latest with the npm dist-tag add command

[BenoitAverty]

I can't use this workflow unfortunately. My project is not a NPM library and it's not released on any NPM registry. My real artifact is a docker image.

Moreover, the entire release process can't be executed in one go because of infrastructure constraints: some steps (deploying the review app for example) must be executed in a particular context to be able to deploy to kubernetes, the deploy part must be in a single gitlab job so I can re-deploy or rollback with gitlab's features, etc.

I understand this may not really be the use case this library is intending to solve, so if you think it's outside the scope, I would understand and you can feel free to close this issue (I'll be able to hack something and solve my problem).

I still think it could be useful to have some way to configure the script's output to make it easier to parse when doing a dry run (Doing a dry run is the way to solve my use case as mentionned in the faq by the way).

for example

$ semantic-release -d --quiet --show-version
next version: 0.2.0

or something like that (my example is ugly, only to illustrate)

[pvdlg]

In most cases where such feature was requested there was a better solution to implement the desired workflow, so it hasn't been implemented so far.

It seems the workflow explained here is very specific and uncommon. However we might consider adding such feature if there is other workflow that would require it.

So if anyone using a workflow that would benefit from that feature, please add a comment to this issue to explain your workflow with as much detail as possible.

[ghost]

In most cases where such feature was requested there was a better solution to implement the desired workflow, so it hasn't been implemented so far.

I'm not sure I completely agree with that statement. In previous versions this was sometimes hacked together using pre and post sub commands, e.g.

"release": "semantic-release pre && npm run build && npm publish && semantic-release post"

Obviously not an ideal solution. So I'm happy to see there's FAQ now and some other approaches as mentioned in the first few responses above.

@BenoitAverty imho if you're not using this product for NPM please consider looking for a less opinionated product, many of which have been mentioned in older issues related to version numbers.

[gr2m]

I agree with @pvdlg, we can leave the issue open for some more time to see if others have a similar workflow, but I can’t recall anyone form the past

[BenoitAverty]

@jhabdas I tried other libs but semantic-release is the only one that is this high-level. I thought it would be less work to implement the compte workflow (parse commits, determine version bump, generate changelog, release) by configuring semantic-release that by redoing the same work with, for example, conventional-changelog.

I still think it was easier, but maybe it's less elegant because it's a lot of configuration.

[andresmijares]

the feature would be extremely useful for me as well. I need the next version printed in several places and run scripts with this value.

[pvdlg]

@andresmijares could you explain your workflow and why such feature would be useful to you?

[andresmijares]

Sure thing, I'm using the package to manage release for another project in a different language, this is going to build the proyect and publish in our artifact repository name as the version, which mean that in order to build the distribution I need to pass the version number. I've tried to create a script that takes this version number and make something like:

"release": {
   "prepare": [{
       "path": "@semantic-release/exec",
       "cmd": "./build.sh --release -v ${version}"
   }]
}

which I thought it would work but I havent had any luck with it.

[pvdlg]

Can you clarify what "I havent had any luck with it" means?
Is it not working? What's the problem?

[pvdlg]

btw, as indicated in semantic-release/exec#usage the proper syntax is ${nextRelease.version} not ${version}.
So your config should be:

"release": {
   "prepare": [{
       "path": "@semantic-release/exec",
       "cmd": "./build.sh --release -v ${nextRelease.version}"
   }]
}

[andresmijares]

my bad, I just figured I had 1 issue not related to the package, it worked like charm, I decided to use ${version} since it is the one marked for tag-format sample.

Thank you for the comment!

[deyceg]

@BenoitAverty I do something like you, and end up just using a bit of sed/awk magic to cat the next version (if there is one) to a VERSION file.

We have an npm library, that is consumed by some app, which is deployed to a review environment if on a feature branch. This allows us to publish the npm package under package_name@next when developing against a feature

[gurpreetatwal]

Just wanted to drop my vote for this feature as well. I have a couple of restrictions on my workflow that prevent me from using semantic-release fully without this feature.

• my "package" is a web server, so it is not pushed to npm
• for security / compliance no code is allowed to be deployed unless it has gone through a review process meaning a bot can't edit files before merging to master and deploying
• I need to have the version number in the package.json for my service for things like error tracking, logging, etc.

The workflow I was thinking is as follows:

1. add a git post-commit hook that runs on every commit created, it runs semantic-release and amends the previous commit to have the updated package.json file
2. when a commit lands on master, semantic-release runs in CI and creates the github release with release notes

I've run into two problems with this:

1. The need to maintain two different semantic-release configs, one for local use and one for CI use.
2. semantic-release will not execute if my branch is behind my remote

This is the setup I have thus far:

'use strict';

module.exports = {
  verifyConditions: [],
  analyzeCommits: ['@semantic-release/commit-analyzer'],
  verifyRelease: [
    {
      path: '@semantic-release/exec',
      cmd: 'echo  ${nextRelease.version} > .version',
    },
  ],
  generateNotes: [],
  prepare: [],
  publish: [],
  success: [],
  fail: [],
};

# compute the version from the commit message
npx semantic-release --dry-run --branch "$( git rev-parse --abbrev-ref HEAD )" --no ci

# update package.json & package-lock.json
## note: the subshell is needed because you can't read and write to the same file
echo "$(jq ".version = \"$( cat .version )\"" package.json )" > package.json
echo "$(jq ".version = \"$( cat .version )\"" package-lock.json )" > package-lock.json
git add package.json package-lock.json

# disable post-commit hook temporarily, otherwise ammending the commit will execute this again
[ -x "$hook" ] && chmod -x "$hook"
git commit --amend --allow-empty
chmod +x "$hook"

I could get around the limitation by using standard-version, but then the tool publishing the tag would different from the one bumping the versions.

Ideally I would run semantic-release -d --quiet --show-version and semantic-release would analyze the commits between the last tag on GitHub and HEAD and then just print the recommended version.

I will say that this breaks most of the assumptions that semantic-release is built upon, meaning it runs in a CI environment, but maybe introducing a local flag would make the abstraction cleaner?

Another idea would be to implement this via a plugin of some sort, but the checking of various git states is actually in the main semantic-release code rather than a plugin which can be disabled.

[Blackclaws]

I also stumbled across semantic-release because I really like the idea of having version numbers detached from human emotions. However in our case we are building a Unity application and need to build both an android and an ios binary out of it.

So our complete process is something like:

1. Determine Version of Build
2. Set version number in unity
3. Perform Unity Build
4. Perform Android and iOS builds
5. Semantic Release Tag
6. Deploy build artifacts to app stores

Unfortunately this cannot all be done on the same machine let alone in one process. Especially building iOS apps requires a macOS machine while the Unity Build takes place in a Kubernetes cluster. The build number also needs to be set before the build process starts.

I totally understand that the initial use case for semantic-release is basically releasing an npm package and the language of semantic-release is identical to the package system being used. There are a lot of cases where this luxury doesn't exist.

Having to hack around instead of just having a simple option that prints the expected version is a bit sad. Even if semantic-release is opinionated it appears to be in widespread enough use that you might consider all the people that don't use it for npm packages but have build systems that semantic-release simply doesn't support or have a multistage pipeline in their CI system that requires the version before a final release.

[srosato]

I also have a workflow use case using next.js and the nx monorepo tool.

In next.js it is easy to add an app version at build time using the generateBuildId function in next.config.js.

For example:

module.exports = withNx({
  generateBuildId: async () => {
    const pkgVersion = JSON.parse(readFileSync(`${__dirname}/../package.json`).toString()).version
    return semver.parse(pkgVersion).version
  },
  webpack: (config, { buildId }) => {
      config.plugins.push(
      new webpack.DefinePlugin({
        'process.env.APP_VERSION': buildId
      })
    );

    return config;
  },
});

And then, in say, a gitlab pipeline file, I usually would run the following:

yarn nx affected:lint --base=$AFFECTED_BASE --parallel
yarn nx format:check --base=$AFFECTED_BASE --parallel
yarn nx affected:test --base=$AFFECTED_BASE --parallel

if [ $CI_COMMIT_REF_NAME == "$CI_DEFAULT_BRANCH" ]; then
    yarn semantic-release
fi

yarn nx affected --target=export --base=$AFFECTED_BASE --parallel

The problem is, the build can still fail at exporting and generating the static files. But then I will have already added the tag to the repository. What I would like to do is write to package.json, generate the CHANGELOG.md, then export and make my actual release with next.js and if it passes, then we can publish the tag. If it fails at exporting, nobody will care because the version will never be released so it eliminates the concern about mutable releases.

Edit:

Using @xesf approach, I'm able to workaround this like this:

plugins:
  [
      '@semantic-release/commit-analyzer',
      '@semantic-release/release-notes-generator',
      '@semantic-release/changelog',
    [ '@semantic-release/npm', { npmPublish: false } ],
    [
        '@semantic-release/exec',
      {
        prepareCmd: 'yarn nx affected --target=export --base=$AFFECTED_BASE --parallel',
      },
    ],
    [
        '@semantic-release/git',
      {
        assets: [ 'package.json', 'CHANGELOG.md' ],
        message: "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}",
      },
    ],
      '@semantic-release/gitlab',
  ]

[JoA-MoS]

@srosato you can check out my approach here

https://semantic-release-plus.gitbook.io/semantic-release-plus/recipes/utility/expected-next-version

You will have to use the semantic-release-plus fork of semantic-release - https://www.npmjs.com/package/semantic-release-plus. Notice the skipTag prop in the prerelease config.

This may also interest you - https://semantic-release-plus.gitbook.io/semantic-release-plus/recipes/monorepos/nx-monorepo

[gabisrm]

Hi,
I've read over the comments and I think I'm ahaving a similar issue. Our project is Gitlab based, where the pipeline is:

1. Build the code with the next version calculated by semantic release. This version needs to be included in package.json, as it is used across the application.
2. Tests are executed
3. If successful, then it is deployed in a dev environment for our QA department to test
4. When QA gives the OK, we publish to the production environment. At this point, the version may be rejected, and a new version must be published, restarting the workflow again.
5. On this stage, a Gitlab Release and tag is created and pushed.

What I really need is to execute the plugins independently, on different stages:

• On stage 1, execute @semantic-release/commit-analyzer and @semantic-release/npm with npmPublish: false
• On stage 5, execute @semantic-release/release-notes-generator and @semantic-release/gitlab to publish to gitlab.

Is there any chance that semantic-release allows for independent execution of the configured plugins?

[Blackclaws]

Yes it does (kinda). Basically use --dry-run.

We have the following step:

semantic-versioning:
  stage: determine-version
  image: node:latest
  script:
    - npm i
    - npx semantic-release --dry-run
    - test -f version.env
  artifacts:
    reports:
      dotenv: version.env

With this .releaserc.yaml

plugins:
   - "@semantic-release/commit-analyzer"
   - "@semantic-release/release-notes-generator"
   - [ "@semantic-release/changelog",
      {
         "changelogFile": "CHANGELOG.md"
      } ]
   - - "@semantic-release/exec"
     - verifyReleaseCmd: "./.release-utils/verifyRelease.sh ${nextRelease.version}"
   - - "@semantic-release/gitlab"
     - gitlabUrl: https://redacted
   - - "@semantic-release/git"
     - assets: [ "CHANGELOG.md", "package.json" ]
       message: "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"

and this script:

echo "NEXT_VERSION=$1" > version.env

I have tried to get it to work with directly passing an echo command to semantic release but that didn't work due to shell issues.

[DanySK]

I hit this issue as well. It surprises me that it is so requested and that it was integrated in a fork, but it can't make it into the main distribution.

[kristof-mattei]

@DanySK which fork?

[Blackclaws]

@DanySK which fork?

https://semantic-release-plus.gitbook.io/semantic-release-plus

[JoA-MoS]

To be specific this recipe https://github.com/semantic-release-plus/semantic-release/blob/master/docs/recipes/expected-next-version.md

[maxiride]

Chiming in the conversation to bring up another way to achieve the result described in the subject.

This solution uses Github workflow specific commands, namely the example-defining-outputs-for-a-job.

1. Use the exec plugin to store the semantic release ${nextRelease.version} variable in a github workflow step output:
   In .releaserc.json;

...
    ["@semantic-release/exec",
      {
        "publishCmd": "echo ::set-output name=nextVer::${nextRelease.version}"
      }
    ]

2. Declare a new joboutput in the workflow yml file:

...
      - name: run semantic release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release
        id: ver
    outputs:
      output1: ${{ steps.ver.outputs.nextVer }}

3. Use the step output in another job:

  print:
    needs: release
    runs-on: ubuntu-20.04
    steps:
      - name: print version
        run: echo ${{ needs.release.outputs.output1}}

---

Full running example

Workflow: https://github.com/maxiride/semantic-release-test/blob/4d330f2d46408f2019c33661f7f67f3e836f7bd1/.github/workflows/outputs.yml

Semantic Release configuration file: https://github.com/maxiride/semantic-release-test/blob/4d330f2d46408f2019c33661f7f67f3e836f7bd1/.releaserc.json

Example run: https://github.com/maxiride/semantic-release-test/actions/runs/1755300704

---

This method is pretty hacky but gets the job done. Nonetheless a semantic release built-in method would be more future proof to use. An official Github Action with proper inputs and outputs would be even more appreciated.

[DanySK]

This is a very nice strategy, too. The differences with the force-push approach are that:

1. those cloning the repo do not get the annotated tag
2. processes requiring an annotated tag to work (e.g., based on git describe) won't work

[dgroh]

Much easier like suggested earlier:

export NEXT_VERSION=$(npx semantic-release --dry-run | grep 'The next release version is' | sed -E 's/.* ([[:digit:].]+)$/\1/')
echo $NEXT_VERSION

Still, waiting for a proper solution!

[Twipped]

@maxiride Have you worked out a way to do this in a pull request? I keep running into a problem where it does not recognize the PR as being one of the approved branches, even if I do branches: ['*'] and noCi.

This test run was triggered on the branch refs/pull/1/merge, while semantic-release is configured to only publish from main, therefore a new version won’t be published.

[nunocalaim]

thanks for everyone that showed how to get the version parsed, or created a fork, or created a one liner. This was very helpful. Thanks also for the original developers of the tool! You did an amazing job! It would just be more amazing if you incorporated this massive feedback of adding this simple functionality

[paambaati]

An official Github Action with proper inputs and outputs would be even more appreciated.

Not official, but an action that makes the next version available as a step output on Github Actions is here –
https://github.com/felipecrs/semantic-release-export-data

[doughlass]

An issue that is 5 years old and we still don't have an official way of outputting the value.

[n0th1ng-else]

I solved it for my et project by writing own local semantic-release plugin. for example

// <project-root>/release-exec.js
import { writeFileSync } from "fs";

const verifyRelease = async (_, context) => {
  const next = context.nextRelease.version;
  // do whatever you want with this new version. let's say we save it into .VERSION file
  writeFileSync(".VERSION", next);
};

export default {
  verifyRelease,
};

And then in the semantic-release config file

// <project-root>/release.config.js
export default {
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/github",
    "./release-exec.js",
  ],
};

[ManuelRauber]

Adding my vote here as well.

It's a pretty common use case to show the version number and possibly the change log in the app, that must be created before the build.

[vinmassaro]

I am using this plugin to update the version number in a file in the repo: https://github.com/jpoehnelt/semantic-release-replace-plugin

[haarism]

It seems the workflow explained here is very specific and uncommon. However we might consider adding such feature if there is other workflow that would require it.

Scenario:
Nx running builds against a github action matrix for a bunch of apps/libraries/packages.
After each build, saving artifact and downloading them in another job which publishes the artifact takes time. You will see that in gitHub actions often this is true based on size of files you want to save. So instead each build-X publishes the build artifact to an external artifactory (or say S3) , to publish this it need the future version number. So I agree that at this stage the version no is invalid, but let the consumer of semantic version decide when to dry run and when to run the final ?

If one of the app/lib fails, we don't want to bump the mono-repo version, and it is easy to remove/invalidate the artifact file.
Or we have to do a version '-pending' and renaming the artifact when all builds succeed.
However, in my case some of these are apps and want to start using these builds in pre-prod layer and a tentative version number is needed for that. Once version becomes invalid, we can roll back the build deployed- or label it dirty. All this is for speeding up the release pipelines.

So if along with --dry --no-ci which we are grateful for, can we get a --json option ?

[kristof-mattei]

In most cases where such feature was requested there was a better solution to implement the desired workflow, so it hasn't been implemented so far.

It seems the workflow explained here is very specific and uncommon. However we might consider adding such feature if there is other workflow that would require it.

So if anyone using a workflow that would benefit from that feature, please add a comment to this issue to explain your workflow with as much detail as possible.

For me, what's important is that I ship artifacts and not source code. If a certain build is approved by QA, vetted by security etc, then it is THAT build that should be released.

A build of the same source code is not the same. Because of all the systems that we work with reproducible builds aren't a thing yet.

We tag the artifact with all the checksums of the tools used, and they might differ if we choose to release a 3 day old build. Rebuilding them just for the sake of releasing introduces unnecessary risk.

So when we build something, we pre-calculate the version number and add it in the binary.

When we then choose to release a certain tag we do not need to rebuild the binary. It is tagged with a commit and a version number.

And we get to tell our customers that the binary they're getting is the same the one we tested throughout all our environments.

[haarism]

@kristof-mattei I have the following workflow based on “trunk based development” on a monorepo that has many web apps and libs.

Workflow

1. quick merges to main with “as good as we can do” build which pass QA automation and DevSecOps pipeline
2. There are several merges in parallel and merge group and merge queue of enterprise github is used to merge to main
3. Main is considered prod ready although not released to PROD. Any feature merged either works at prod scale or fails and blocks teams who are constantly on top of integegating things fast as priority. So all main merge is deployed to PREPROD continuously.
4. While that deployment is propogated (20 min in amplify a static generation representative pages and rest incremental) further manual and deep scans need to be done on the artifact - this is a release candidate this need to have a semetic version. And if this final deep QA and Secuity fails the build is reverted from PREPROD. Integrate fast and fail fast is the motto.

This is not a core engine or some complex application - its mostly a bunch of high performing static websites that rely on shared libraries. Here I also don't want to just semantic upgrade only for release/*app branches. I need to be able to leverage main as a source of tracking.

I'm open to feedback if you think I can use semantic release any other way.

Currently I'm scraping semantic release dry run output. A machine readable json seems to be lesswrong than having none.

[zachspar]

You can use this plugin that sets GitHub Action output variables to be consumed in later steps or jobs.