Skip to content

Commit 6df7b29

Browse files
gladiuscodegladiuscode
authored
feat: improve docs (#13)
* docs: improve release-it-setup * docs: improve pass-artifacts-to-next-jobs * docs: fix typo * docs: improve pull-request-code-checks
1 parent e386b9a commit 6df7b29

File tree

3 files changed

+55
-185
lines changed

3 files changed

+55
-185
lines changed

‎docs/pass-artifacts-to-next-jobs.md

Lines changed: 10 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,16 @@
11
# Pass artifacts to next jobs
22

3-
When you have a workflow with multiple jobs and you need to pass artifacts (products) from one job to the next ones,
4-
you can use the `needs` keyword and a couple of actions from the GitHub Marketplace.
3+
This document describes how to pass artifacts from one job to the next ones.
54

6-
The `needs` keyword allows you sequence the jobs in a workflow. You can specify that a job can only run after another
7-
job has completed successfully. This is required when you need to pass artifacts from one job to another.
5+
Artifacts are the files created by a job that you want to persist after the job has completed. They may be log files or
6+
build outputs that you want to include in a release, for example in a npm package as the product of `tsc`.
87

9-
To actually pass the artificats, you can use the `upload-artifact` and `download-artifact` actions from the GitHub
10-
Marketplace. The `upload-artifact` action allows you to upload a file or directory as an artifact. The `download-artifact`
11-
action allows you to download an artifact from a previous job.
8+
When you have a workflow with multiple jobs, and you need to pass artifacts from one job to the next ones, you need to
9+
use the `needs` keyword to sequence your job to run after a previous one has completed and a couple of actions from the
10+
GitHub Marketplace.
1211

13-
Take a look at the following example:
12+
To pass the artifacts, you can use the [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact)
13+
actions from the GitHub Marketplace. The `upload-artifact` action allows you to upload a file or directory as an artifact,
14+
while the `download-artifact`action allows you to download an artifact from a previous job.
1415

15-
```yaml
16-
17-
name: pass-artifacts-to-next-jobs
18-
19-
on: workflow_dispatch
20-
21-
jobs:
22-
build:
23-
name: Build
24-
runs-on: ubuntu-latest
25-
26-
steps:
27-
- name: Checkout
28-
uses: actions/checkout@v4
29-
30-
- name: Setup
31-
uses: ./.github/actions/setup
32-
33-
- name: Build
34-
run: yarn build
35-
36-
- name: Upload Build Artifact
37-
uses: actions/upload-artifact@v4
38-
with:
39-
name: build-artifact
40-
path: build
41-
42-
run-build:
43-
name: Run build
44-
runs-on: ubuntu-latest
45-
needs: build
46-
47-
steps:
48-
- name: Checkout
49-
uses: actions/checkout@v4
50-
51-
- name: Setup
52-
uses: ./.github/actions/setup
53-
54-
- name: Download Build Artifact
55-
uses: actions/download-artifact@v4
56-
with:
57-
name: build-artifact
58-
59-
- name: Run
60-
# This assumes that your build artifacts is an index.js
61-
run: node index.js
62-
63-
```
16+
Take a look at the workflow here: [.github/workflows/pass-artifacts-to-next-jobs.yml](../.github/workflows/pass-artifacts-to-next-jobs.yml)

‎docs/pull-request-code-checks.md

Lines changed: 10 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,18 @@
11
# Pull request code checks
22

3-
When a new pull request is opened against the main branch, it is a good idea to run some checks on the code to make sure
4-
that it is up to the standards of the project.
5-
You can run it on every push, but it is better to run it only when a pull request is approved, to avoid reaching the
6-
limits of the Github Actions free tier.
7-
8-
Take a look at the following example:
9-
10-
```yaml
11-
12-
name: pull-request-code-checks
13-
14-
on:
15-
# (1) Run the workflow only when a pull request is:
16-
# - opened against the main branch
17-
# - and a review is submitted
18-
pull_request_review:
19-
branches:
20-
- main
21-
types: [ submitted ]
3+
This document explains how to run code checks on a pull request.
224

23-
jobs:
24-
build:
25-
name: Build
26-
runs-on: ubuntu-latest
5+
## Prerequisites
276

28-
steps:
29-
- name: Checkout
30-
uses: actions/checkout@v4
7+
- You have configured the required scripts to run the checks;
318

32-
- name: Setup
33-
uses: ./.github/actions/setup
34-
35-
- name: Build
36-
run: yarn build
37-
38-
lint:
39-
name: Lint
40-
runs-on: ubuntu-latest
41-
42-
steps:
43-
- name: Checkout
44-
uses: actions/checkout@v4
45-
46-
- name: Setup
47-
uses: ./.github/actions/setup
9+
When a new pull request is opened against the main branch, it is a good idea to run some checks on the code to make sure
10+
that it is up to the standards of the project, before merging it.
4811

49-
- name: Lint
50-
run: yarn lint
12+
You can run it on every push, but it is better to run it only when a pull request is approved, to avoid reaching the
13+
limits of the Github Actions free tier.
5114

52-
```
15+
The workflow provided by this repository runs eslint and typescript checks each time someone submits a review on a pull
16+
request.
5317

18+
Take a look at the workflow here: [.github/workflows/pull-request-code-checks.yml](../.github/workflows/pull-request-code-checks.yml)

‎docs/release-it-setup.md

Lines changed: 35 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,53 @@
1-
## If you allow direct pushes to the main branch
1+
# Release It Setup
22

3-
```yaml
3+
This document describes how to set up [release-it](https://github.com/release-it/release-it) to run in a Github Actions workflow.
44

5-
name: release
5+
## Prerequisites
66

7-
on: workflow_dispatch
7+
- You have installed [release-it](https://github.com/release-it/release-it) in your project;
8+
- You have a `release` script in your `package.json` that runs `release-it` with --ci flag;
89

9-
jobs:
10+
Depending on your repository settings, you may need to set up a [Github App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)
11+
to create a token that allows release-it to push on main, bypassing the branch protection rules that require pull requests.
12+
The Github App needs to be installed on the repository and have the `Contents`, `Actions` and `Administration` permissions
13+
to properly work.
1014

11-
release:
12-
name: Release
13-
runs-on: ubuntu-latest
14-
needs: build
15+
If you need to publish to npm too, you need to create an automation token to authenticate with npm and bypass the 2FA
16+
requirement. You can create an automation token directly in the [npm website](https://www.npmjs.com/).
1517

16-
# (1) Give GIT_TOKEN permission to push to the repository
17-
# By default, the GITHUB_TOKEN does not have permission to push to the repository
18-
permissions:
19-
contents: write
18+
## Available Workflows
2019

21-
steps:
22-
- name: Checkout
23-
uses: actions/checkout@v4
20+
### release-it-without-pr-only
2421

25-
# This is a custom action that sets up the environment
26-
- name: Setup
27-
uses: ./.github/actions/setup
22+
This workflow showcases how to set up release-it on a repository with an unprotected main branch. It doesn't require any
23+
particular setup, as the GITHUB_TOKEN, with content permissions set to write, is enough to push to the main branch.
2824

29-
# (2) Configure a git user to make the release
30-
# This is required to identify the user
31-
- name: Configure Git User
32-
run: |
33-
git config --global user.name "${GITHUB_ACTOR}"
34-
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
25+
Take a look at the workflow here: [.github/workflows/release-it-without-pr-only.yml](../.github/workflows/release-it-without-pr-only.yml)
3526

36-
- name: Release
37-
run: yarn release
38-
env:
39-
# (3) Provide the GITHUB_TOKEN to release-it
40-
# This is required to identify the user who made the release
41-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
27+
### release-it-with-pr-only
4228

43-
```
29+
This workflow showcases how to set up release-it on a repository with a ruleset that only allows PRs to the main branch.
30+
It needs a GitHub App added to the bypass list of the ruleset and a token created by the GitHub App to push to the
31+
main branch using the [actions/create-github-app-token](https://github.com/actions/create-github-app-token) action.
32+
This token is then used to checkout the main branch and push the changes made by release-it.
4433

45-
## If you don't allow direct pushes to the main branch
34+
Before running this workflow, you need to add both the GitHub App id and private key secrets to your repository with the
35+
values associated with the GitHub App you created.
4636

47-
You need to create a GitHub App and add it to the bypass list in your rules.
48-
See [here](https://github.com/orgs/community/discussions/13836#discussioncomment-8535364)
37+
> [!IMPORTANT]
38+
> If you are using this workflow in a repository owned by an organization, you need to create an organization-wide GitHub
39+
> App.
4940
50-
```yaml
41+
Take a look at the workflow here: [.github/workflows/release-it-with-pr-only.yml](../.github/workflows/release-it-with-pr-only.yml)
5142

52-
name: release
53-
54-
on: workflow_dispatch
55-
56-
jobs:
57-
58-
release:
59-
name: Release
60-
runs-on: ubuntu-latest
61-
needs: build
62-
63-
steps:
64-
# (1) This action creates a token using the GitHub App
65-
- uses: actions/create-github-app-token@v1
66-
id: app-token
67-
with:
68-
# (1.1) Provide the App ID and Private Key
69-
# Be sure to read the private key value from the .pem file that you downloaded from the GitHub App web page
70-
# upon private key creation. (Not the SHA that you see in the GitHub App web page!!)
71-
app-id: ${{ vars.APP_ID }}
72-
private-key: ${{ secrets.PRIVATE_KEY }}
73-
74-
- name: Checkout
75-
uses: actions/checkout@v4
76-
with:
77-
# (2) Tell checkout to use the token created by the GitHub App
78-
token: ${{ steps.app-token.outputs.token }}
79-
80-
# This is a custom action that sets up the environment
81-
- name: Setup
82-
uses: ./.github/actions/setup
83-
84-
# (3) Configure a git user to make the release
85-
# This is required to identify the user
86-
- name: Configure Git User
87-
run: |
88-
git config --global user.name "${GITHUB_ACTOR}"
89-
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
90-
91-
- name: Release
92-
run: yarn release
93-
env:
94-
# (4) Provide the GITHUB_TOKEN to release-it but use the token created by the GitHub App
95-
# This is required to identify the user who made the release
96-
GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
97-
98-
```
43+
### release-it-with-npm-and-pr-only
9944

45+
This workflow is an extension of the `release-it-with-pr-only` workflow that also publishes the package to npm. It
46+
requires an automation token created in the npm website to authenticate with npm and bypass the 2FA requirement.
47+
It leverages the upload-artifact and download-artifact actions to pass additional build artifacts that needs to be
48+
published as well, like the `build` folder.
10049

50+
Before running this workflow, you need to add the `NPM_ACCESS_TOKEN` secret to your repository with the value of the
51+
automation token.
10152

53+
Take a look at the workflow here: [.github/workflows/release-it-with-npm-and-pr-only.yml](../.github/workflows/release-it-with-npm-and-pr-only.yml)

0 commit comments

Comments
 (0)