diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000..cbd540b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,17 @@ +--- +name: Bug report +about: Create a bug report to help us improve +title: "\U0001F41B [Bug]" +labels: bug +assignees: gladiuscode + +--- + +**Workflow affected** +Please provide the name of the workflow that isn't working properly. + +**Describe the bug** +Please descrive the bug you are experiencing. + +**Screenshots** +If applicable, add screenshots to help explain your problem. diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000..20b6e78 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,11 @@ +--- +name: Feature request +about: Suggest a new workflow that we could create +title: "⚙️ [Feature]" +labels: enhancement +assignees: gladiuscode + +--- + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. diff --git a/.github/workflows/release-it-with-npm-and-pr-only-and-inputs.yml b/.github/workflows/release-it-with-npm-and-pr-only-and-inputs.yml new file mode 100644 index 0000000..ea4e685 --- /dev/null +++ b/.github/workflows/release-it-with-npm-and-pr-only-and-inputs.yml @@ -0,0 +1,95 @@ +name: release-it-with-npm-and-pr-only-and-inputs + +on: + workflow_dispatch: + inputs: + dry-run: + description: 'Run release-it in dry-run mode' + required: false + default: false + type: boolean + +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 + + lint: + name: Lint + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup + uses: ./.github/actions/setup + + - name: Lint + run: yarn lint + + release: + name: Release + runs-on: ubuntu-latest + needs: [build, lint] + + steps: + # (1) Create a GitHub App token + # Note: the Github App must be installed on the repository and included in the bypass list of the ruleset. + - uses: actions/create-github-app-token@v1 + id: app-token + with: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.PRIVATE_KEY }} + + - name: Checkout + uses: actions/checkout@v4 + with: + # (2) Use the GitHub App token to init the repository + token: ${{ steps.app-token.outputs.token }} + # (3) Fetch all history so that release-it can determine the version + fetch-depth: 0 + + - name: Setup + uses: ./.github/actions/setup + + # (4) Configure Git 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: Download Build Artifact + uses: actions/download-artifact@v4 + with: + name: build-artifact + + - name: Release + run: | + if [ ${{ inputs.dry-run }} = true ]; then + yarn release-it --dry-run + else + yarn release-it + fi + env: + # (5) Make GITHUB_TOKEN available to release-it but use the GitHub App token + GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} + # (6) Make NPM_ACCESS_TOKEN available to release-it and npm publish command + NPM_ACCESS_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }} + diff --git a/.github/workflows/release-it-with-npm-and-pr-only.yml b/.github/workflows/release-it-with-npm-and-pr-only.yml new file mode 100644 index 0000000..c088d86 --- /dev/null +++ b/.github/workflows/release-it-with-npm-and-pr-only.yml @@ -0,0 +1,83 @@ +name: release-with-npm-and-pr-only + +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 + + lint: + name: Lint + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup + uses: ./.github/actions/setup + + - name: Lint + run: yarn lint + + release: + name: Release + runs-on: ubuntu-latest + needs: [build, lint] + + steps: + # (1) Create a GitHub App token + # Note: the Github App must be installed on the repository and included in the bypass list of the ruleset. + - uses: actions/create-github-app-token@v1 + id: app-token + with: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.PRIVATE_KEY }} + + - name: Checkout + uses: actions/checkout@v4 + with: + # (2) Use the GitHub App token to init the repository + token: ${{ steps.app-token.outputs.token }} + # (3) Fetch all history so that release-it can determine the version + fetch-depth: 0 + + - name: Setup + uses: ./.github/actions/setup + + # (4) Configure Git 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: Download Build Artifact + uses: actions/download-artifact@v4 + with: + name: build-artifact + + - name: Release + run: yarn release + env: + # (5) Make GITHUB_TOKEN available to release-it but use the GitHub App token + GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} + # (6) Make NPM_ACCESS_TOKEN available to release-it and npm publish command + NPM_ACCESS_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }} + diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..7f0c4e5 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +//registry.npmjs.org/:_authToken=${NPM_ACCESS_TOKEN} diff --git a/.release-it.json b/.release-it.json index 7ba8b92..614c8b7 100644 --- a/.release-it.json +++ b/.release-it.json @@ -7,7 +7,7 @@ "release": true }, "npm": { - "publish": false + "publish": true }, "plugins": { "@release-it/conventional-changelog": { @@ -15,12 +15,10 @@ "name": "angular", "types": { "feat": { - "section": "Features", - "hidden": false + "section": "Features" }, "fix": { - "section": "Bug Fixes", - "hidden": false + "section": "Bug Fixes" } } }, diff --git a/CHANGELOG.md b/CHANGELOG.md index e72a5f3..61d2d97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +# [1.1.0](https://github.com/gladiuscode/github-actions-playground/compare/0.2.0...1.1.0) (2025-02-05) + + +### Bug Fixes + +* release-it-with-npm-and-pr-only-and-inputs workflow step name ([#15](https://github.com/gladiuscode/github-actions-playground/issues/15)) ([3ad77c6](https://github.com/gladiuscode/github-actions-playground/commit/3ad77c6bafcd5aaf5a6abb37a36b259a5d084114)) + + +### Features + +* create issues templates ([#9](https://github.com/gladiuscode/github-actions-playground/issues/9)) ([731bfd5](https://github.com/gladiuscode/github-actions-playground/commit/731bfd544d66c24d4de3082b9e4d058fe8ef4154)) +* create release-it-to-npm-with-pr-only ([#11](https://github.com/gladiuscode/github-actions-playground/issues/11)) ([07e7dfe](https://github.com/gladiuscode/github-actions-playground/commit/07e7dfe89b88d3def350c922e348ff4d932145c1)) +* improve docs ([#13](https://github.com/gladiuscode/github-actions-playground/issues/13)) ([6df7b29](https://github.com/gladiuscode/github-actions-playground/commit/6df7b294458b5e94226e094e38cb2161221ec3ef)) +* release it with npm pr and inputs ([#14](https://github.com/gladiuscode/github-actions-playground/issues/14)) ([9e022e5](https://github.com/gladiuscode/github-actions-playground/commit/9e022e53ec03562c18d1c7ab169407fc424da55a)) + # [0.2.0](https://github.com/gladiuscode/github-actions-playground/compare/0.1.1...0.2.0) (2025-01-26) diff --git a/docs/pass-artifacts-to-next-jobs.md b/docs/pass-artifacts-to-next-jobs.md index d948ec2..004ede2 100644 --- a/docs/pass-artifacts-to-next-jobs.md +++ b/docs/pass-artifacts-to-next-jobs.md @@ -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) diff --git a/docs/pull-request-code-checks.md b/docs/pull-request-code-checks.md index 87abe1c..bce16b3 100644 --- a/docs/pull-request-code-checks.md +++ b/docs/pull-request-code-checks.md @@ -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) diff --git a/docs/release-it-setup.md b/docs/release-it-setup.md index ac3e885..020eb79 100644 --- a/docs/release-it-setup.md +++ b/docs/release-it-setup.md @@ -1,101 +1,60 @@ -## 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 +### release-it-with-npm-and-pr-only -on: workflow_dispatch +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. -jobs: +Before running this workflow, you need to add the `NPM_ACCESS_TOKEN` secret to your repository with the value of the +automation token. - 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 }} - -``` +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) +### release-it-with-npm-and-pr-only-and-inputs +This workflow is an extension of the `release-it-with-npm-and-pr-only` workflow that also takes in an optional input to +test the release process. +Take a look at the workflow here: [.github/workflows/release-it-with-npm-and-pr-only-and-inputs.yml](../.github/workflows/release-it-with-npm-and-pr-only-and-inputs.yml) diff --git a/package.json b/package.json index 9d3cc00..421a733 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,20 @@ { - "name": "github-actions-playground", + "name": "ga-playground", "description": "Playground to learn and save all github-actions template I use on my open source projects.", - "version": "0.2.0", + "version": "1.1.0", "packageManager": "yarn@4.6.0", + "author": "Mirko Quaglia (https://github.com/gladiuscode)", + "main": "build/index", + "source": "src/index", + "files": [ + "src", + "build", + "!**/__tests__", + "!**/__fixtures__", + "!**/__mocks__" + ], "scripts": { - "release": "release-it", + "release": "release-it --ci", "build": "tsc", "lint": "eslint ./src" }, @@ -19,5 +29,20 @@ }, "engines": { "node": "=18.20.6" - } + }, + "keywords": [ + "github-actions", + "github", + "actions", + "playground", + "template" + ], + "repository": { + "type": "git", + "url": "git+https://github.com/gladiuscode/github-actions-playground.git" + }, + "publishConfig": { + "registry": "https://registry.npmjs.org" + }, + "license": "MIT" } diff --git a/yarn.lock b/yarn.lock index 43d8cf0..b351b09 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1718,6 +1718,20 @@ __metadata: languageName: node linkType: hard +"ga-playground@workspace:.": + version: 0.0.0-use.local + resolution: "ga-playground@workspace:." + dependencies: + "@eslint/js": "npm:9.19.0" + "@release-it/conventional-changelog": "npm:10.0.0" + eslint: "npm:9.19.0" + globals: "npm:15.14.0" + release-it: "npm:18.1.2" + typescript: "npm:5.7.3" + typescript-eslint: "npm:8.21.0" + languageName: unknown + linkType: soft + "get-east-asian-width@npm:^1.0.0": version: 1.3.0 resolution: "get-east-asian-width@npm:1.3.0" @@ -1796,20 +1810,6 @@ __metadata: languageName: node linkType: hard -"github-actions-playground@workspace:.": - version: 0.0.0-use.local - resolution: "github-actions-playground@workspace:." - dependencies: - "@eslint/js": "npm:9.19.0" - "@release-it/conventional-changelog": "npm:10.0.0" - eslint: "npm:9.19.0" - globals: "npm:15.14.0" - release-it: "npm:18.1.2" - typescript: "npm:5.7.3" - typescript-eslint: "npm:8.21.0" - languageName: unknown - linkType: soft - "glob-parent@npm:^5.1.2": version: 5.1.2 resolution: "glob-parent@npm:5.1.2"