Skip to content

Commit 03fac6d

Browse files
authored
Adds README. (#9)
1 parent 4454bbc commit 03fac6d

37 files changed

+12528
-3
lines changed
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
40.3 KB
Loading
85.5 KB
Loading
76.6 KB
Loading
34.6 KB
Loading
37.1 KB
Loading
85.3 KB
Loading
Loading
50.5 KB
Loading
32.4 KB
Loading
51.7 KB
Loading
47 KB
Loading
47.3 KB
Loading
39.7 KB
Loading
35.4 KB
Loading
48.8 KB
Loading
38.7 KB
Loading
37.8 KB
Loading
35.6 KB
Loading
41.3 KB
Loading

.github/assets/release-failure.jpg

60.5 KB
Loading

.github/assets/releases.jpg

74.2 KB
Loading

.github/workflows/optimizes-images.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ jobs:
2626
uses: actions/checkout@v2
2727
- name: Optimize images
2828
id: images
29-
uses: calibreapp/image-actions@1.1.0
29+
uses: calibreapp/image-actions@main
3030
with:
3131
compressOnly: ${{ github.event_name != 'pull_request' }}
3232
githubToken: ${{ secrets.GITHUB_TOKEN }}

README.md

+260-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,261 @@
1-
# validate-and-extract-github-release-data-for-publishing-action
1+
# github-releases-for-automated-package-publishing-action
22

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+
![Profile > Access tokens](.github/assets/generate-npm-token-step-1.jpg)
39+
![Generate new token](.github/assets/generate-npm-token-step-2.jpg)
40+
![Generate automation token](.github/assets/generate-npm-token-step-3.jpg)
41+
![Successfully generated a new token!](.github/assets/generate-npm-token-step-4.jpg)
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+
![Profile > Settings](.github/assets/generate-github-token-step-1.jpg)
53+
![Developer settings](.github/assets/generate-github-token-step-2.jpg)
54+
![Personal access tokens](.github/assets/generate-github-token-step-3.jpg)
55+
![Generate new token](.github/assets/generate-github-token-step-4.jpg)
56+
![New personal access token](.github/assets/generate-github-token-step-5.jpg)
57+
![Make sure to copy your new personal access token now. You won't be able to see it again!](.github/assets/generate-github-token-step-6.jpg)
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+
![Repository > Settings](.github/assets/add-github-repository-secret-step-1.jpg)
75+
![Secrets](.github/assets/add-github-repository-secret-step-2.jpg)
76+
![New repository secret](.github/assets/add-github-repository-secret-step-3.jpg)
77+
![Add secret](.github/assets/add-github-repository-secret-step-4.jpg)
78+
![Secret added](.github/assets/add-github-repository-secret-step-5.jpg)
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+
![Profile > Settings](.github/assets/add-github-organization-secret-step-1.jpg)
90+
![New organization secret](.github/assets/add-github-organization-secret-step-2.jpg)
91+
![Add secret](.github/assets/add-github-organization-secret-step-3.jpg)
92+
![Secret added](.github/assets/add-github-organization-secret-step-4.jpg)
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+
![Releases](.github/assets/releases.jpg)
203+
![Draft a new release](.github/assets/draft-a-new-release.jpg)
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+
![New release](.github/assets/create-release-publish-version-step-1.jpg)
215+
![GitHub Actions release workflow logs](.github/assets/create-release-publish-version-step-2.jpg)
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+
![New pre-release](.github/assets/create-release-publish-tagged-version-step-1.jpg)
227+
![GitHub Actions pre-release workflow logs](.github/assets/create-release-publish-tagged-version-step-2.jpg)
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+
![GitHub Actions release workflow failure logs](.github/assets/release-failure.jpg)
243+
![Releases](.github/assets/releases.jpg)
244+
![Release name](.github/assets/handle-release-failure-step-1.jpg)
245+
![Delete release](.github/assets/handle-release-failure-step-2.jpg)
246+
![Delete release confirmation](.github/assets/handle-release-failure-step-3.jpg)
247+
![Delete release success message and tags](.github/assets/handle-release-failure-step-4.jpg)
248+
![Tag name](.github/assets/handle-release-failure-step-5.jpg)
249+
![Delete tag](.github/assets/handle-release-failure-step-6.jpg)
250+
![Delete tag confirmation](.github/assets/handle-release-failure-step-7.jpg)
251+
![Delete tag success message](.github/assets/handle-release-failure-step-8.jpg)
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

Comments
 (0)