Skip to content

feat: improve docs #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 1, 2025
Merged

feat: improve docs #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7daf68d
docs: improve release-it-setup
gladiuscode Feb 1, 2025
36f3b27
docs: improve pass-artifacts-to-next-jobs
gladiuscode Feb 1, 2025
41f7d1b
docs: fix typo
gladiuscode Feb 1, 2025
cfd13bb
docs: improve pull-request-code-checks
gladiuscode Feb 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 10 additions & 57 deletions docs/pass-artifacts-to-next-jobs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,16 @@
# Pass artifacts to next jobs

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

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

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

Take a look at the following example:
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)
actions from the GitHub Marketplace. The `upload-artifact` action allows you to upload a file or directory as an artifact,
while the `download-artifact`action allows you to download an artifact from a previous job.

```yaml

name: pass-artifacts-to-next-jobs

on: workflow_dispatch

jobs:
build:
name: Build
runs-on: ubuntu-latest

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup
uses: ./.github/actions/setup

- name: Build
run: yarn build

- name: Upload Build Artifact
uses: actions/upload-artifact@v4
with:
name: build-artifact
path: build

run-build:
name: Run build
runs-on: ubuntu-latest
needs: build

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup
uses: ./.github/actions/setup

- name: Download Build Artifact
uses: actions/download-artifact@v4
with:
name: build-artifact

- name: Run
# This assumes that your build artifacts is an index.js
run: node index.js

```
Take a look at the workflow here: [.github/workflows/pass-artifacts-to-next-jobs.yml](../.github/workflows/pass-artifacts-to-next-jobs.yml)
55 changes: 10 additions & 45 deletions docs/pull-request-code-checks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,18 @@
# Pull request code checks

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
that it is up to the standards of the project.
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
limits of the Github Actions free tier.

Take a look at the following example:

```yaml

name: pull-request-code-checks

on:
# (1) Run the workflow only when a pull request is:
# - opened against the main branch
# - and a review is submitted
pull_request_review:
branches:
- main
types: [ submitted ]
This document explains how to run code checks on a pull request.

jobs:
build:
name: Build
runs-on: ubuntu-latest
## Prerequisites

steps:
- name: Checkout
uses: actions/checkout@v4
- You have configured the required scripts to run the checks;

- name: Setup
uses: ./.github/actions/setup

- name: Build
run: yarn build

lint:
name: Lint
runs-on: ubuntu-latest

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup
uses: ./.github/actions/setup
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
that it is up to the standards of the project, before merging it.

- name: Lint
run: yarn lint
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
limits of the Github Actions free tier.

```
The workflow provided by this repository runs eslint and typescript checks each time someone submits a review on a pull
request.

Take a look at the workflow here: [.github/workflows/pull-request-code-checks.yml](../.github/workflows/pull-request-code-checks.yml)
118 changes: 35 additions & 83 deletions docs/release-it-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,101 +1,53 @@
## If you allow direct pushes to the main branch
# Release It Setup

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

name: release
## Prerequisites

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

jobs:
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)
to create a token that allows release-it to push on main, bypassing the branch protection rules that require pull requests.
The Github App needs to be installed on the repository and have the `Contents`, `Actions` and `Administration` permissions
to properly work.

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

# (1) Give GIT_TOKEN permission to push to the repository
# By default, the GITHUB_TOKEN does not have permission to push to the repository
permissions:
contents: write
## Available Workflows

steps:
- name: Checkout
uses: actions/checkout@v4
### release-it-without-pr-only

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

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

- name: Release
run: yarn release
env:
# (3) Provide the GITHUB_TOKEN to release-it
# This is required to identify the user who made the release
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
### release-it-with-pr-only

```
This workflow showcases how to set up release-it on a repository with a ruleset that only allows PRs to the main branch.
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
main branch using the [actions/create-github-app-token](https://github.com/actions/create-github-app-token) action.
This token is then used to checkout the main branch and push the changes made by release-it.

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

You need to create a GitHub App and add it to the bypass list in your rules.
See [here](https://github.com/orgs/community/discussions/13836#discussioncomment-8535364)
> [!IMPORTANT]
> If you are using this workflow in a repository owned by an organization, you need to create an organization-wide GitHub
> App.

```yaml
Take a look at the workflow here: [.github/workflows/release-it-with-pr-only.yml](../.github/workflows/release-it-with-pr-only.yml)

name: release

on: workflow_dispatch

jobs:

release:
name: Release
runs-on: ubuntu-latest
needs: build

steps:
# (1) This action creates a token using the GitHub App
- uses: actions/create-github-app-token@v1
id: app-token
with:
# (1.1) Provide the App ID and Private Key
# Be sure to read the private key value from the .pem file that you downloaded from the GitHub App web page
# upon private key creation. (Not the SHA that you see in the GitHub App web page!!)
app-id: ${{ vars.APP_ID }}
private-key: ${{ secrets.PRIVATE_KEY }}

- name: Checkout
uses: actions/checkout@v4
with:
# (2) Tell checkout to use the token created by the GitHub App
token: ${{ steps.app-token.outputs.token }}

# This is a custom action that sets up the environment
- name: Setup
uses: ./.github/actions/setup

# (3) Configure a git user to make the release
# This is required to identify the user
- name: Configure Git User
run: |
git config --global user.name "${GITHUB_ACTOR}"
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"

- name: Release
run: yarn release
env:
# (4) Provide the GITHUB_TOKEN to release-it but use the token created by the GitHub App
# This is required to identify the user who made the release
GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

```
### release-it-with-npm-and-pr-only

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

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

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)