|
1 | | -# validate-and-extract-github-release-data-for-publishing-action |
| 1 | +# github-releases-for-automated-package-publishing-action |
2 | 2 |
|
3 | | -GitHub Action for validating and extracting GitHub release data, used for publishing JavaScript pacakges via a GitHub Action workflow using yarn or npm. |
| 3 | +> GitHub Action to validate and extract GitHub release information, used for automated package publishing. |
| 4 | +
|
| 5 | +There are several ways to do automated releases and package publishing via GitHub actions, but many of them have drawbacks, at least in my opinion. |
| 6 | + |
| 7 | +- Many other GitHub Actions and [manually running a workflow](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) only allow publishing from the default branch (ie. `master` or `main`). |
| 8 | +- Other guides and GitHub Actions allow for publishing on any branch by looking for changes to the `version` in `package.json` on the `push` event, but this lacks protection from just anyone opening a PR and publishing a new version. |
| 9 | +- [GitHub's publishing node packages guide](https://docs.github.com/en/actions/guides/publishing-nodejs-packages) doesn't enforce keeping `version` in `package.json` synchronized with the GitHub release. |
| 10 | +- True pre-releases, with npm tags (ie. `package@beta`, `package@canary`, etc.) aren't supported. |
| 11 | + |
| 12 | +This GitHub Action was created to overcome these limitations and gaps. This action, paired with the `release` GitHub Action event, will: |
| 13 | + |
| 14 | +- Ensure release drafts won't cause a package to be published. |
| 15 | +- Ensure git tags start with a `v`, like `npm version` and `yarn version`. |
| 16 | +- Ensure that the `version` in `package.json` matches the release being created. |
| 17 | +- Ensure versions are valid [semver](https://semver.org/) format. |
| 18 | +- Ensure the GitHub release is marked as a prerelease if the semver version has a prerelease tag. |
| 19 | +- Allow only users with write permissions to create releases. |
| 20 | +- Allow packages to be published from any branch, which is great for publishing pre-releases before code is merged into the default branch. |
| 21 | +- Allow full control on how to publish, without assuming anything, like yarn vs. npm, NPM registry vs. GitHub Packages registry, running additional validation or build steps prior to publishing, etc. |
| 22 | + |
| 23 | +## Usage |
| 24 | + |
| 25 | +### Generate a Package Registry Token |
| 26 | + |
| 27 | +Whether you're using [NPM](https://www.npmjs.com/) or [GitHub Packages](https://github.com/features/packages) as your package registry, you'll need to generate a token that will allow automated publishing of your package. This token will be used in your GitHub Actions workflow, as we'll see later below. |
| 28 | + |
| 29 | +> **_Note_**: These tokens should be treated with care. If exposed or compromised, they can be used maliciously as they have the power to publish code on your behalf. Never commit them to your repository or share them with others. |
| 30 | +
|
| 31 | +<details> |
| 32 | + <summary>How to Generate an NPM Token</summary> |
| 33 | + |
| 34 | +You'll need to generate a new token in your NPM account, which will allow automated publishing of packages. |
| 35 | + |
| 36 | +The screenshots below will visually walk you through the process. |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | +</details> |
| 44 | + |
| 45 | +<details> |
| 46 | + <summary>How to Generate a GitHub Token</summary> |
| 47 | + |
| 48 | +You'll need to generate a new token in your GitHub account, which will allow automated publishing of packages. |
| 49 | + |
| 50 | +The screenshots below will visually walk you through the process. |
| 51 | + |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | + |
| 59 | +</details> |
| 60 | + |
| 61 | +### Add Package Registry Token to GitHub Secrets |
| 62 | + |
| 63 | +Once you have a registry token, you need to add that token to GitHub so it can be used in GitHub Action workflows. This can be done one of two ways, either on a repository (only option available for personal accounts, which unfortunately means you'll need to do this for each repository you want to automate releases / publishing for) or as a shared secret for an entire GitHub organization. |
| 64 | + |
| 65 | +You would use either `NPM_TOKEN` or `GITHUB_TOKEN` for the secret name, depending on what package registry you're using. |
| 66 | + |
| 67 | +<details> |
| 68 | + <summary>How to Add Secrets to a Repository</summary> |
| 69 | + |
| 70 | +Since your token is sensitive information, you'll need to store it in GitHub as a secret. Individual accounts will need to add secrets to each repository. |
| 71 | + |
| 72 | +The screenshots below will visually walk you through the process. |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +</details> |
| 81 | + |
| 82 | +<details> |
| 83 | + <summary>How to Add Secrets to a GitHub Organization</summary> |
| 84 | + |
| 85 | +Since your token is sensitive information, you'll need to store it in GitHub as a secret. Organizations can store secrets at the organization level, meaning it will be accessible to all repositories within the organization. |
| 86 | + |
| 87 | +The screenshots below will visually walk you through the process. |
| 88 | + |
| 89 | + |
| 90 | + |
| 91 | + |
| 92 | + |
| 93 | + |
| 94 | +</details> |
| 95 | + |
| 96 | +### Add a GitHub Action Workflow for Automated Publishing of Packages |
| 97 | + |
| 98 | +`github-releases-for-automated-package-publishing-action` will output the following properties, which you can use in your GitHub Action workflow. |
| 99 | + |
| 100 | +#### version |
| 101 | + |
| 102 | +> string |
| 103 | +
|
| 104 | +The version of the package to publish. |
| 105 | + |
| 106 | +Examples: `1.2.3`, `1.2.3-beta.1` |
| 107 | + |
| 108 | +#### tag |
| 109 | + |
| 110 | +> string |
| 111 | +
|
| 112 | +Extracted tag of a version. |
| 113 | + |
| 114 | +For example, a version of `1.2.3-beta.1` would extract `beta` for the tag. |
| 115 | + |
| 116 | +Package dependencies can be installed using version tags, such that `<package>@<tag>` will install the latest version with that tag. This is typically done for pre-releases or early access releases. |
| 117 | + |
| 118 | +Read [npm-dist-tag](https://docs.npmjs.com/cli/v6/commands/npm-dist-tag) for more information on version tags and how to use them. |
| 119 | + |
| 120 | +Default: `''` (empty string) |
| 121 | + |
| 122 | +Examples: `beta`, `canary` |
| 123 | + |
| 124 | +#### Example |
| 125 | + |
| 126 | +Below is an example of a GitHub Actions workflow. |
| 127 | + |
| 128 | +As you can see, we look for the `release` event, specifically, the `created` release type. |
| 129 | + |
| 130 | +The code below is just an example. You can leverage `github-releases-for-automated-package-publishing-action` output for publishing however you want. |
| 131 | + |
| 132 | +```yaml |
| 133 | +name: release |
| 134 | +on: |
| 135 | + release: |
| 136 | + types: [created] |
| 137 | +jobs: |
| 138 | + release: |
| 139 | + runs-on: ubuntu-latest |
| 140 | + steps: |
| 141 | + # Checkout the exact commit tagged on the release. |
| 142 | + - name: Checkout repo |
| 143 | + uses: actions/checkout@v2 |
| 144 | + with: |
| 145 | + ref: ${{ github.event.release.target_commitish }} |
| 146 | + |
| 147 | + # This is the action in this repo! 👇 |
| 148 | + # Note we set an `id` called `release`. We'll use that later... |
| 149 | + - name: Validate and extract release information |
| 150 | + id: release |
| 151 | + uses: manovotny/github-releases-for-automated-package-publishing-action@v1.0.0 |
| 152 | + |
| 153 | + # When setting the node version for publishing a release, it's also impotant |
| 154 | + # to set `always-auth` and `registry-url` too. I've encountered vauge errors |
| 155 | + # and publishing doesn't work unless they are supplied. |
| 156 | + # |
| 157 | + # This example is using NPM's registry. If you were publishing to GitHub's |
| 158 | + # Package registry, you'd use `https://npm.pkg.github.com` instead. |
| 159 | + - name: Set node version |
| 160 | + uses: actions/setup-node@v1 |
| 161 | + with: |
| 162 | + always-auth: true |
| 163 | + node-version: '12.x' |
| 164 | + registry-url: 'https://registry.npmjs.org' |
| 165 | + |
| 166 | + # Perform installs, run tests, run a build step, etc. here, as needed. |
| 167 | + |
| 168 | + # The last two steps will publish the package. Note that we're using |
| 169 | + # information from the `release` step above (I told you we'd use it |
| 170 | + # later). Notice the `if` statements on both steps... |
| 171 | + # |
| 172 | + # If there *is* a tag (ie. `beta`, `canary`, etc.), we publish a |
| 173 | + # "pre-release" or "tagged" version of a package (ie. 1.2.3-beta.1). |
| 174 | + # |
| 175 | + # If there *is not* a tag (ie. `beta`, `canary`, etc.), we publish a |
| 176 | + # version of a package (ie. 1.2.3). |
| 177 | + # |
| 178 | + # This example is using yarn to publish, but you could just as easily |
| 179 | + # use npm, if you prefer. It's also publishing to the NPM registry, |
| 180 | + # thus, it's using `NPM_TOKEN`, but you could just as easily use |
| 181 | + # `GITHUB_TOKEN` if you were publishing to the GitHub Package registry. |
| 182 | + |
| 183 | + # This will publish a "pre-release" or "tagged" version of a package. |
| 184 | + - name: Publish tagged version |
| 185 | + if: steps.release.outputs.tag != '' |
| 186 | + run: yarn publish --new-version ${{ steps.release.outputs.version }} --tag ${{ steps.release.outputs.tag }} |
| 187 | + env: |
| 188 | + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} |
| 189 | + |
| 190 | + # This will publish a version of a package. |
| 191 | + - name: Publish version |
| 192 | + if: steps.release.outputs.tag == '' |
| 193 | + run: yarn publish --new-version ${{ steps.release.outputs.version }} |
| 194 | + env: |
| 195 | + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} |
| 196 | +``` |
| 197 | +
|
| 198 | +### Create a Release to Publish a Package |
| 199 | +
|
| 200 | +With all of the above in place, publishing a package is as easy as creating a new release on the repository. |
| 201 | +
|
| 202 | + |
| 203 | + |
| 204 | +
|
| 205 | +From there, you need to decide what kind of release you want to make. |
| 206 | +
|
| 207 | +<details> |
| 208 | + <summary>How to Publish a Version</summary> |
| 209 | +
|
| 210 | +Creating a new GitHub release will start the automated publishing process. |
| 211 | +
|
| 212 | +The screenshots below will visually walk you through the process. |
| 213 | +
|
| 214 | + |
| 215 | + |
| 216 | +
|
| 217 | +</details> |
| 218 | +
|
| 219 | +<details> |
| 220 | + <summary>How to Publish Pre-Release / Tagged Version</summary> |
| 221 | +
|
| 222 | +Creating a new GitHub release will start the automated publishing process. To create a pre-release / tagged version, you'll need to use the proper pre-release / tagged semver syntax and mark the release as a pre-release. |
| 223 | +
|
| 224 | +The screenshots below will visually walk you through the process. |
| 225 | +
|
| 226 | + |
| 227 | + |
| 228 | +
|
| 229 | +</details> |
| 230 | +
|
| 231 | +<details> |
| 232 | + <summary>How to Handle Release Failures</summary> |
| 233 | +
|
| 234 | +In the event a publish fails for a release due to validation issues or for some other reason, rolling back the release is relatively easy. |
| 235 | +
|
| 236 | +1. Delete the corresponding release and tag from GitHub. |
| 237 | +1. Address the underlying issues that cause the failure. |
| 238 | +1. Try creating a release again. |
| 239 | +
|
| 240 | +The screenshots below will visually walk you through the process. |
| 241 | +
|
| 242 | + |
| 243 | + |
| 244 | + |
| 245 | + |
| 246 | + |
| 247 | + |
| 248 | + |
| 249 | + |
| 250 | + |
| 251 | + |
| 252 | +
|
| 253 | +</details> |
| 254 | +
|
| 255 | +## Related |
| 256 | +
|
| 257 | +Be sure and check out my [github-actions-experiments](https://github.com/manovotny/github-actions-experiments) repo where I mess around with other concepts to enhance your GitHub Actions workflows and experience! |
| 258 | +
|
| 259 | +## License |
| 260 | +
|
| 261 | +MIT © [Michael Novotny](http://manovotny.com) |
0 commit comments