GitHub Action

[bcoe]

New feature motivation

I've been playing a bit with GitHub actions, my motivation being to show off how an automated tagging/CHANGELOG generation workflow can chain together with actions/npm.

So far I've been prototyping with standard-version, which is a CLI tool I wrote that handles tagging/CHANGELOG generation via-Conventional Commit Messages.

The prototype is here...

It feels like it would potentially make more sense for the action to use some combination of semantic-release actions...

New feature description

I was thinking perhaps semantic-release could be broken out into individual actions, each running as individual steps in a GitHub workflow ... here's my dream world:

1. run a travis-ci action that fans out tests on a variety of platforms.

if the build is successful ...

1. run a semantic-release action that handles tagging.
2. run a semantic-release action that handles CHANGELOG generation. (optionally).
3. run a semantic-release action that mints the GitHub release (optionally).
4. run the actions/npm action to handle publishing to npm.

New feature implementation

Curious what other folks think, CC: @hbetts, @gajus, @joshk, @nickvanw, @zeke

[pvdlg]

What would be the point of breaking down semantic-release into multiple pieces that could run individually?

semantic-release is already modular thanks to plugins: https://github.com/semantic-release/semantic-release/blob/multi-branches/docs/usage/plugins.md

Instead a GitHub action could be one that runs when all CI pass (is that possible by the way?) and that just run npx semantic-release.

The workflow you describe is already possible via the config plugins: ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm']. To generate a CHANGELOG.md file and include it in the npm package, add @semantic-release/changelog to the plugins list. To commit the CHANGELOG.md to your repo, add @semantic-release/git to the plugins list. To create a release on GitHub and comment on included issues/PRs add @semantic-release/github to the plugins list.

Breaking down semantic-release into multiple piece as you suggest would be quite complex to do and make us loose a lot of features. Currently the each plugins are orchestrated and called by the core and there is some dependencies, for example:

• If the publish step of a plugin fails we call the fail step with the corresponding Error, that allow to open an issue on GitHub for example
• For each successful publish we call the success plugins with information related to each release (URL, name, plugin that made the release, commits, etc...), that allow for example to add comments on issue and PR included in a release
• The generateNotes plugins (the default one can use conventional commits or other presets) are called and the resulting notes are passed to all publish plugins
• There is a prepare plugin step that allow to generate or modify files, that can be published by the publish plugins

The problem with having all those steps running in different processes is that we cannot pass much information between them other than the version released (via the tag itself). The current plugin system allow a lot more flexibility and advanced features. In addition, I don't see how configuring several actions is beneficial versus configuring a list of plugins. Finally the current plugin system allow to work and be modular with any Git host (GitLab, Bitbucket, custom server) and to deploy to any package manager.

That said, if you provide compelling reasons to go that direction we'll certainly consider it!

[bcoe]

@pvdlg I think the plugin system pretty much works the way I was envisioning, it sounds like if (as an example) I instead wanted to publish the npm module using actions/npm, I could just setup the following config:

['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator'].

And opt out of the npm step -- I think a compelling GitHub action would potentially just be a container with semantic-release installed, reasonable defaults, and the ability to modify behavior somewhat with environment variables.

Instead a GitHub action could be one that runs when all CI pass (is that possible by the way?) and that just run npx semantic-release.

@joshk is working on a proof of concept that would provide a full-featured Travis CI test run, in the form of an action.

---

Should I attempt to see https://github.com/conventional-commits/conventional-commits-action over the finish line, and we could potentially reference it as one of the recipes? Or would you rather create your own action, and I'd happily contribute?

[pvdlg]

I instead wanted to publish the npm module using actions/npm, I could just setup the following config:

Yes you can exclude the @semantic-release/npm plugin to opt out of publishing to npm, and then run your action to do that.
But by doing so you loose the following semantic-release features:

• Includes a link to the npm registry in the comments added to issue and PR included (if you were to use the @semantic-release/github plugin)
• Warn the user of the npm publish error (for example by opening an issue on GitHub with the @semantic-release/github plugin)

So again, what would be the point?

I think a compelling GitHub action would potentially just be a container with semantic-release installed, reasonable defaults, and the ability to modify behavior somewhat with environment variables.

That's already the case. By running npx semantic-release you have by default ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']. You cannot customize that by environment variable but you can via configuration file or CLI args.

This is why I suggested that a semantic-release action would just run npm semantic-release. It could also allow to pass parameters as CLI args.

Should I attempt to see https://github.com/conventional-commits/conventional-commits-action over the finish line, and we could potentially reference it as one of the recipes? Or would you rather create your own action, and I'd happily contribute?

conventional-commits-action seems more limited than what semantic-release do now (multiple commit convention, multiple plugins etc...). We won't reference it as a recipe in the semantic-release repo as it's a different tool even though it's doing something similar. It might be of use for folks who want a simpler/lighter solution though.

We will most likely create a GitHub action that runs npx semantic-release $* in the future. Probably when my request to access the beta is approved :-) Contributions are always welcome :-)

The code should be extremely simple though:

FROM node:10-slim

LABEL....

COPY "entrypoint.sh" "/entrypoint.sh"
ENTRYPOINT ["/entrypoint.sh"]

#!/bin/sh

set -e
sh -c "npx semantic-release $*"

[bcoe]

@pvdlg most of the complexity in the container I shared is adding support for the hub CLI, so that you can easily git push using just the GITHUB_TOKEN that is populated in github actions; I believe that semantic-release invokes the git bin as well, so would want something similar.

It seems like semantic-release would be an incredible use-case for actions, did you see this tweet; also perhaps you can reach out to @nickvanw or @zeke.

[pvdlg]

GitHub actions would be really beneficial for semantic-release if they would allow to:

• run semantic-release only after multiple CIs repost a success status
• Allow to have access to GITHUB_TOKEN for pull request originating from a forked repo, so we could add comments on PR with info regarding the version that would be released when the PR is merged

I don't know if that's possible though. Without those two things, running semantic-release in any CI or a GitHub action is pretty much he same thing.

[hutson]

multiple CIs

@pvdlg do you mean external CIs? (Such as Travis CI, etc.)

Allow to have access to GITHUB_TOKEN for pull request

I would assume not, but I haven't confirmed that myself.

[pvdlg]

do you mean external CIs? (Such as Travis CI, etc.)

Yes

I would assume not, but I haven't confirmed that myself.

Same. I'd be curious to know. Currently the only solution is a GitHub app, which come with limitation (no file system, can't run user code)

[hutson]

In the case of a simple npm package, I did the following:

workflow "Default" {
  on = "push"
  resolves = "Deliver"
}

action "Node_6_Install" {
  runs = "yarn"
  uses = "docker://node:6"
}

action "Node_6_Test" {
  needs = "Node_6_Install"
  runs = "yarn test"
  uses = "docker://node:6"
}

action "Node_8_Install" {
  runs = "yarn"
  uses = "docker://node:8"
}

action "Node_8_Test" {
  needs = "Node_8_Install"
  runs = "yarn test"
  uses = "docker://node:8"
}

action "Node_10_Install" {
  runs = "yarn"
  uses = "docker://node:10"
}

action "Node_10_Test" {
  needs = "Node_10_Install"
  runs = "yarn test"
  uses = "docker://node:10"
}

action "Default_Branch" {
  needs = ["Node_6_Test", "Node_8_Test", "Node_10_Test"]
  uses = "actions/bin/filter@master"
  args = "branch master"
}

action "Deliver" {
  args = "--preset $(pwd)/node_modules/@hbetts/conventional-changelog-config"
  needs = "Default_Branch"
  secrets = ["GITHUB_TOKEN"]
  uses = "DOCKER IMAGE"
}

There was no need to wait on external CI providers because GitHub Actions became my CI. My Deliver job waited on the filter job (which just checks that I only release on the master branch), and the filter job waited on my Node test matrix.

Anyway, it's just an example of how I imagine I could hook semantic-release docker image into the Deliver action and have the confidence that it will only run on successful builds on the master branch.

(Please ignore the --preset args, as it's just a demonstration of how I pass in a custom conventional-changelog preset into the image I actually use for generating releases in a private GitHub repo)

[hutson]

If external CI is needed, then maybe @joshk's work would provide an Action that demonstrates how to call out to Travis-CI to trigger CI jobs on that platform.

In that case, I then imagine that I might have a Travis CI Action for calling out to Travis CI and running my Travis CI test matrix, and then another action that calls out to maybe AppVeyor to execute my test matrix on that platform.

Then I would fan those back into a semantic-release Action.

[hutson]

I imagine this would also translate well to offering a semantic-release Docker image for GitLab where all CI is handled through their .gitlab-ci.yaml configuration file (in which you can specify an image for semantic-release, and fan-in all the CI jobs you might have, including from your custom runners that might be running on OSX, Windows, etc.)

[pvdlg]

All that doesn't provide additional value versus any CI as most CI offer a mechanism to orchestrate jobs.

One benefit that GitHub actions could bring would be to run something when all check status on the HEAD are successful. So it would allow for example to run semantic-release only after Travis CI and Appveyor and Codecov are successful for example.

[bcoe]

One benefit that GitHub actions could bring would be to run something when all check status on the HEAD are successful. So it would allow for example to run semantic-release only after Travis CI and Appveyor and Codecov are successful for example.

I agree, I think GitHub actions are made much more valuable once there's a clear story regarding how you can wire them together with a variety of external services. Travis CI, or AppVeyor, etc., have the benefit of running on a large matrix of platforms, providing information about past failures, etc.

Similarly services like Codecov or Coveralls.io provide useful historical information about the quality of a codebase over time.

Allow to have access to GITHUB_TOKEN for pull request originating from a forked repo, so we could add comments on PR with info regarding the version that would be released when the PR is merged

Yeah, can't imagine how this wouldn't be a security nightmare ... what is cool about GitHub actions is they do magically populate the GITHUB_TOKEN for the repo they're installed on, and the code is already cloned into the working directory by the time your action runs.

[pvdlg]

I agree, I think GitHub actions are made much more valuable once there's a clear story regarding how you can wire them together with a variety of external services. Travis CI, or AppVeyor, etc., have the benefit of running on a large matrix of platforms, providing information about past failures, etc.

Basically I'd like a trigger like check_all that would run the action when all Check API status are successful. It doesn't seems that exist: events-supported-in-workflow-files

@bcoe do you think there is some workaround or a solution to achieve a similar workflow?

The solution I planned to implement is a GitHub app that list for Check API events, and when all are successful create a branch, that would in turn trigger the a CI job that runs semantic-release.

what is cool about GitHub actions is they do magically populate the GITHUB_TOKEN for the repo they're installed on, and the code is already cloned into the working directory by the time your action runs.

Yes that's the cool part, however is it guaranteed? What happen when you run the action on pull_request events and you open a PR from a forked repo?
Does it just run with an empty GITHUB_TOKEN? Doest it run at all? Or does it run it with the GITHUB_TOKEN somehow?
Basically, do you have to handle that case when you develop an action?

[gudmundur]

@hbetts I'm not sure that the Node_*_Install actions have the effect that you intend. Since all of the actions in a workflow share a workspace, won't they all be installing to the same node_modules folder, quite potentially at the same time?

If that's the case, what would your semantic expectation be for what happens?

[gudmundur]

Allow to have access to GITHUB_TOKEN for pull request

I would assume not, but I haven't confirmed that myself.

The GitHub token you get is an installation token scoped to the repository which the workflow runs on. What this means is that you can't post anything to the forked repo, but you can have workflows run on the forked repo (given they are flagged in to the beta as well).

[shawnbot]

FYI, I put a bit of thinking into this last week as we're (the GitHub Primer team) interested in using semantic-release within an Actions workflow. (Different teams and individuals obviously have different needs, but I was curious to see if we could ween ourselves off Travis entirely and do everything on GitHub.) The setup is pretty simple:

1. The workflow breaks each of the npm commands up into a different sequential task using actions/npm: install (or ci, which is a bit faster), run lint, then test.
2. The final, sequential release task should just run npx semantic-release (or npm run semantic-release). The CLI know when it's not on the release branch(es), so it won't publish from any others.

TL;DR: it's basically doable, but not without custom actions and some environment variable tweaks. Here's what I ran into:

1. I had to create a new action that installs the git binary from the same node:10-slim image as actions/npm.

2. To maintain parity with the actions/npm environment, I copied that action's entrypoint.sh and "aliased" NPM_TOKEN (which semantic-release expects) to NPM_AUTH_TOKEN.

3. I had to call semantic-release with --no-ci because it doesn't seem to recognize the Actions environment as CI (maybe because it doesn't set a CI environment variable?).

4. To get around the lack of push permissions for the built-in GITHUB_TOKEN, I created a personal access token with full repo permissions and added it as a GH_TOKEN secret. (Just to be safe, I also disabled the automatic GITHUB_TOKEN in this task.)

   This is a bummer because it makes everything on GitHub happen on my behalf rather than the actions bot account. (Of course, anyone running semantic-release on Travis has already run into this and probably uses a dummy "bot" account's access token, so...)

I was able to make this action work after all of this, but it was more of a headache than I'd expected; and I'm not entirely happy with everything using my personal access token (IMO, the built-in access token is one of the reasons to use Actions over Travis in the first place). In its current state, it's definitely not ready for prime-time.

If anyone is looking to run tests on Travis and then semantic-release in an action, I would suggest looking into a command that waits for Travis's commit status (or check) to pass before running. The ideal would be to have the semantic-release action only run on the check_run event and if the check was a successful Travis run, but — and @gudmundur, please correct me on this — I believe we only run actions on push events for public repos right now.

[hutson]

I had to call semantic-release with --no-ci

@shawnbot could you export CI=true in your Dockerfile, entrypoint.sh, or in the configuration for the Action?

To get around the lack of push permissions for the built-in GITHUB_TOKEN

Is this for pushing a commit to the repository where the version field in package.json is updated?

[shawnbot]

@shawnbot could you export CI=true in your Dockerfile, entrypoint.sh, or in the configuration for the Action?

Yes, I think that would work too. I mostly noted that for my colleagues working on Actions, though, who may be interested in exporting that environment variable by default, e.g. as CI=github.

To get around the lack of push permissions for the built-in GITHUB_TOKEN

Is this for pushing a commit to the repository where the version field in package.json is updated?

Yep! semantic-release plugins could theoretically commit other files too, though, right?

[bddckr]

Indeed they can!

[mcolyer]

I believe we only run actions on push events for public repos right now.

That's correct.

[pvdlg]

@shawnbot great to know that you are looking to use semantic-release with Primer!

We'll definitely provide a GitHub action at some point. But there was no urgency on our side as long as actions are in beta.

I had to create a new action that installs the git binary from the same node:10-slim image as actions/npm.
Yes git is required and there is no easy way around that as we want to preserve compatibility with non-GitHub repos. But when we provide our own semantic-release action that shouldn't be a problem.

To maintain parity with the actions/npm environment, I copied that action's entrypoint.sh and "aliased" NPM_TOKEN (which semantic-release expects) to NPM_AUTH_TOKEN.
Yes semantic-release require the variable to be named NPM_TOKEN. I'm not sure what's the point of maintaining parity with actions/npm. Once we provide our own semantic-release action the variable will have to be named NPM_TOKEN.

I had to call semantic-release with --no-ci because it doesn't seem to recognize the Actions environment as CI (maybe because it doesn't set a CI environment variable?).
The CI we support are listed here: https://github.com/pvdlg/env-ci#supported-ci. We'll add support to GitHub actions.

To get around the lack of push permissions for the built-in GITHUB_TOKEN, I created a personal access token with full repo permissions and added it as a GH_TOKEN secret. (Just to be safe, I also disabled the automatic GITHUB_TOKEN in this task.)

That's kind a problem...I though the GH_TOKEN provided by the action would have sufficient permissions.... semantic-release needs at a minimum to push tags to your repo. And depending on the plugins you are using, it might also need to push commits.

Do you know what are the permission of the GH_TOKEN provided by the action?
Is GitHub plan to have that configurable (in a better way than by setting your personal token?).

[shawnbot]

@pvdlg You're absolutely right about the token permissions being a problem. The bug, however, is actually on our end: it's that the permissions.push field of the API response is wrong, not that the token actually lacks permissions. @ptoomey3 tracked this down and we're working on a fix. 🍻

[joakimhellum]

Hi, thanks for sharing thoughts and experiences about GitHub Action for semantic-release.
We experienced the same. However we also tried to skip the verifyConditions steps hoping the special GITHUB_TOKEN actually did have the push permission anyway, and then we got the following error when trying to push git tag:

refusing to allow an integration to create .github/main.workflow 

But when looking further this seems to be a general problem in GitHub Actions and not only related to the special GITHUB_TOKEN, for example the same seem to happen when using deploy keys.
I don't understand if this restriction is intentional and only during beta, or if this is the bug @shawnbot is referring to.

[11:15:41 PM] [semantic-release] › ✖  An error occurred while running semantic-release: { Error: Command failed: git push --tags https://github.com/some-organization/some-repo.git
To https://github.com/some-organization/some-repo.git
 ! [remote rejected] v1.9.0 -> v1.9.0 (refusing to allow an integration to create .github/main.workflow)
error: failed to push some refs to 'https://github.com/some-organization/some-repo.git'
...

Update: Found a twitter message that suggests this is a bug. Thanks,

[shawnbot]

@joakimhellum-in I ran into the same issue working on some non-semantic-release actions this week, and have confirmed with the team that this is a known bug.

[gr2m]

@shawnbot I’ve learned from @JasonEtco that he successfully pushed to a repository using this form https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git, is this something we should try? Or shall we wait until GitHub resolves it

[JasonEtco]

@gr2m to be clear - that solution will let you push no problem, but will still be blocked from pushing main.workflow files.

[cycjimmy]

I just wrote an action based on semantic-release@^15 and it looks work well for me.

[rarkins]

Do actions work now with the default GitHub token secret in actions? Ie no need to manually add a personal access token for semantic release to work?

[gr2m]

no need to manually add a personal access token for semantic release to work?

No, it works with GITHUB_TOKEN if you use the default configuration. I only need to setup a personal access token if I need to push changes back to master branch and the branch is protected.

See also the discussion at #1317

[cycjimmy]

There is a problem wants help.
When trying to use some commands after semantic-release goes through in Github Actions, an unexpected error occurred: "Failed to replace env in config: ${NPM_TOKEN}". I don't know why this error occurred.

Related Issue: cycjimmy/semantic-release-action#2

[rarkins]

semantic release may be leaving a .npmrc file in the repo once it’s done. Maybe just add a rm -f .npmrc step after releasing

[cycjimmy]

semantic release may be leaving a .npmrc file in the repo once it’s done. Maybe just add a rm -f .npmrc step after releasing

@rarkins It looks work well!

[filipesilva]

I've been using @cycjimmy's https://github.com/cycjimmy/semantic-release-action and it's been working pretty well. The only setup for it that I did was running https://github.com/semantic-release/cli, answering the questions, then adding the GH_TOKEN and NPM_TOKEN to the repository secrets. I also had to set my npm 2fa to auth only (as described in an issue around here somewhere).

[rarkins]

The problem described was only for someone running npm or yarn after semantic-release.

[pvdlg]

I think most of the issue discussed there have been fixed (including not leaving a .npmrc behind).
In addition a recipe was written to use GitHub actions: https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/github-actions.md

IS there anything missing? Or should we close this issue?

[vxna]

Docs suggests to create a workflow with .github/workflows/release.yml and user may assume if he had other workflows like main, test, etc it's a good idea to create another workflow even it wasn't said in plain text. For example I already see such behavior on octokit/rest.js with two separate workflows for testing and releasing.

What's the matter? Docs also claims that:

GitHub Actions support Workflows, allowing to run tests on multiple Node versions and publish a release only when all test pass.

I did some experiments and this is not true. Failing tests on one workflow wouldn't stop semantic-release from creating a release running on other workflow even in context of same commit. I haven't found docs on workflow ordering but it seems they're not related to each other.

Perhaps semantic-release on GitHub Actions should be configured the same way as it already works on CircleCI and Travis CI, using jobs with some adjustments due to GitHub Actions defaults:

A workflow run is made up of one or more jobs. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the jobs.<job_id>.needs keyword.

I already saw two articles suggesting multi-workflow setup for semantic-release and I had no expected results with such configuration.

Maybe I am missing something and this is expected behavior but I think it's unclear.

[pvdlg]

@gr2m can you help on that?
If we can't guarantee that semantic-release run only if all test passes we should't fix the config in the recipe or not recommend it.

[vxna]

@pvdlg I've tested my proposed single workflow and it works correctly on failed and passed tests.

[gr2m]

I will have a look after the holidays

[gr2m]

Docs suggests to create a workflow with .github/workflows/release.yml and user may assume if he had other workflows like main, test, etc it's a good idea to create another workflow even it wasn't said in plain text. For example I already see such behavior on octokit/rest.js with two separate workflows for testing and releasing.

I do two separate workflows, because my setup guarantees that changes are only merged into master when all tests are passing, that workflow is enforced with branch protection. There is no need to run all the same tests again on master, after they passed on a pull request.

I still think we should create our own semantic-release action, there are some good actions out there already, but as sensitive tokens are passed to the action, people are hesitant to use actions from owners they don't know. Maybe we could invite one of the existing action to be moved to semantic-release and enforce a review workflow. Or make one ourselves, it shouldn't require a lot of code.

The only benefit I see from using Actions is that a semantic-release action can provide outputs such as a flag if a version was released and what version.

I think outputs feature introduced in Actions v2 would also make it possible to create more modular GitHub actions as suggested by @bcoe in the original issue. But that's out of scope for now

[rarkins]

@gr2m I would still like to sanity check my master branch (which I release from) and test it before releasing. With a separate release.yml, that doesn't seem to be possible? i.e. I would want release.yml to "depend on" test.yml.

I also thought about whether GitHub's long-supported-but-rarely-used deployments API could be a good fit for this, but didn't find any relevant hits either. i.e. master branch triggers a deployment, and then the deployment event triggers the release action (instead of a push event triggering it).

[gr2m]

I would want release.yml to "depend on" test.yml.

I usually use the branch protection settings to enforce a PR workflow for everyone, including the "Require branches to be up to date before merging " setting. Then I no longer run tests on master

I don't know of a built-in way where release.yml could require another workflow to run first. What you could do is to have the tests workflow create a dispatch event which in turn the release workflow could be triggered by. Note that you have to authenticate using an OAuth Token (or personal access token) when creating the dispatch event, otherwise no action will react on it.

You can create the dispatch event fairly easily using https://github.com/octokit/request-action/

I also thought about whether GitHub's long-supported-but-rarely-used deployments API could be a good fit for this

You could use that as an alternative to the dispatch event, but I think the dispatch event would work better in this case