Forem: OctoLab Team

Automate Releases with Semantic Release and GitHub Actions (Step-by-Step)

OctoLab Team — Sat, 30 Aug 2025 11:36:10 +0000

One of the most common uses of GitHub Actions in Node.js projects is to automate releases: calculate the next version, tag the repository, generate release notes and publish a GitHub Release (and optionally publish to NPM).

This release flow usually involves a few key steps:

Install dependencies to ensure the project can build.
Build the project if your package/app requires compiled artifacts.
Run Semantic Release to analyze commits, bump the version (major/minor/patch), create a tag and publish the release notes.

In this article we will set up a GitHub Actions workflow that automates this process every time you push to main. We will explain step by step what each part of the workflow does and why it is important.

🎯 The purpose of the workflow

We want that, every time a push happens in our main branch, a set of tasks runs to automate releases using Conventional Commits:

Analyzes commit messages and determines the next version (major/minor/patch)
Creates a Git tag and generates release notes
Publishes a GitHub Release
(Optional) Publishes to npm if configured via plugins

🧬 General workflow structure

name: Releasing with Semantic Release

on:
  push:
    branches:
      - main

jobs:
  release:
    name: release
    runs-on: ubuntu-latest
    steps:
      - id: checkout-step
        name: Checkout code
        uses: actions/checkout@v4

      - id: setup-node-step
        name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - id: install-dependencies-step
        name: Install dependencies
        run: npm install

      - id: build-step
        name: Build package
        run: npm run build

      - id: semantic-release-step
        name: Release with Semantic Release
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
        run: npx semantic-release

⚙️ What parts compose a GitHub Actions workflow?

Before going into detail, it is useful to understand how a GitHub Actions workflow is structured. The main elements are:

Trigger (on:)
Defines when the workflow is executed. It can be when pushing, opening a pull request, publishing a release, executing manually, etc.
In our case, we use push to main, which triggers a release attempt every time new commits land in the main branch.

Job (jobs:)
Each workflow can have one or several jobs. A job is a set of tasks that are executed in the same environment.
All the steps of a job share the same filesystem and context. In our example, we have a single job called release.

Runner (runs-on:)
It is the operating system where the job is executed. GitHub provides hosted runners, such as ubuntu-latest, windows-latest or macos-latest, but we also have the possibility to use self-hosted runners.

Steps (steps:)
These are the actions or commands that are executed within a job. They can be:

Reusable actions such as actions/checkout or actions/setup-node.
Specific commands defined with run, such as npm install or npx semantic-release.

🪜 Step-by-step of our workflow

Now that we understand how a workflow is structured, let's analyze each of the steps that make up our workflow. We will see what each action does, why it is necessary and what additional configurations we could apply depending on the case.

on: push (branches: main)

This block indicates that the workflow will be triggered when you push to main. Semantic Release will then decide whether a new release should be created based on the commit history (using Conventional Commits).

uses: actions/checkout@v4

This step downloads the code from the repository so that it is available within the runtime environment.

Some additional options that this action allows are:

fetch-depth: 0 clones the entire repository history (by default only the current commit). Semantic Release may benefit from full history in some setups.
ref: branch-name** you can set a specific branch
path: subdirectory clone the code in a specific path

For this case, just use it without extra configuration:

- uses: actions/checkout@v4

uses: actions/setup-node@v4

This action installs a specific version of Node.js, in our case version 22. It also allows you to configure dependency caching and more.

- uses: actions/setup-node@v4
  with:
    node-version: "22"

Other useful options are:

cache: ‘npm’ enables dependency caching using actions/cache underneath
check-latest: true** forces to use the latest available version that complies with the semver.

Working scripts

- run: npm install
- run: npm run build
- run: npx semantic-release

These steps execute the commands defined in your project and run Semantic Release to automate the versioning and release process:

npm install will install all the project's dependencies.
npm run build** will generate the final package or artifacts if your project needs a build step (libraries, apps, compiled bundles, etc.).
npx semantic-release will: -- analyze commits following Conventional Commits, -- determine the next version (major/minor/patch), -- create a Git tag, -- generate release notes, and -- publish a GitHub Release (and optionally publish to npm if configured via plugins).

💡 Token & config tips

Expose a token with permissions to create tags/releases: env: { GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} } You can also use the default GITHUB_TOKEN with proper write permissions.

Provide a Semantic Release configuration (in package.json under release or in a .releaserc file) with the plugins you need (e.g., @semantic-release/github, @semantic-release/changelog, @semantic-release/npm, @semantic-release/git).

Ensure your commit messages follow Conventional Commits so Semantic Release can infer the correct next version.

✅ Final result

With this flow you guarantee that every push to main goes through an automated release process, without manual tagging or copy-pasting release notes. You can integrate it with additional plugins/steps such as:

Automatic CHANGELOG.md updates and commits
npm publishing with @semantic-release/npm
Multi-branch release strategies (e.g., next, beta)
Notifications (Slack, Discord, etc.)

🐙 Do you want to avoid writing it by hand? There is a more convenient way

Understanding how a workflow works in GitHub Actions is indispensable. It gives you control and helps you customize everything to your needs.

Now... if you don't feel like struggling with the syntax, that's fine too.
At OctoLab we offer you the ability to set up this same flow visually: you choose the actions, fill in the fields and it generates the YAML for you on the fly.

✅ Without indentation errors
✅ With built-in validations
✅ Copy, paste and go.

🧠 Conclusion

This workflow is an excellent basis for automated, reliable releases in Node.js projects. It can be easily adapted to other needs: publishing to npm, updating changelogs automatically, multi-branch strategies, or running on multiple Node versions.

If you prefer to use OctoLab we will be very grateful for your feedback! 🤗

Deploy your application on Vercel with GitHub Actions

OctoLab Team — Wed, 20 Aug 2025 16:52:15 +0000

A very common CI/CD pattern for frontend apps is: build in CI and deploy to production automatically when the code reaches main.
If you use Vercel, you can do this with a short and reliable GitHub Actions workflow that:

downloads your project's configuration and variables from Vercel,
builds the app in CI,
and deploys the already built artifacts to production.

In this article, we'll walk through it step by step and I'll give you some tips to help you understand what each line does.

🎯 Purpose of the workflow

Every time there is a push to main, the following should be executed:

Pull config from Vercel (includes production environment variables).
Reproducible build in CI.
Deploy that artifact (without rebuilding in Vercel).

This will give you predictable deployments that are easy to audit and debug.

🧬 General workflow structure

name: Vercel PRO deployment
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: deploy
    runs-on: ubuntu-latest
    steps:
      - id: checkout-step
        name: Checkout code
        uses: actions/checkout@v4
      - id: install-vercel-cli-step
        name: Install Vercel CLI
        run: npm install --global vercel@latest
      - id: pull-vercel-env-info-step
        name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN
          }}
      - id: build-vercel-artifacts-step
        name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy-vercel-artifacts-step
        name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

💡 Prerequisites
Create the secret VERCEL_TOKEN in your repository (Settings → Secrets and variables → Actions).
Either commit .vercel/project.json, or provide VERCEL_ORG_ID and VERCEL_PROJECT_ID as secrets when you do vercel pull.

🪜 Step by step

on: push (to main)
Each push to main triggers the production pipeline. If you prefer to only deploy when merging by PR, simply avoid pushing directly to main.

uses: actions/checkout@v4
Download your code to the runner so that the following tools (Vercel CLI) have it available.

npm install --global vercel@latest
Install the Vercel CLI.

💡 Tip: to avoid surprises, you can set version: vercel@xx (or whatever you use on your team).

vercel pull --yes --environment=production
Bring the project configuration and production environment variables to .vercel/ on the runner.
In CI there are no interactive questions, so we use --yes.

You need:

.vercel/project.json in the repository or
VERCEL_ORG_ID and VERCEL_PROJECT_ID as variables/secrets.

vercel build --prod
Builds in CI using your framework (Next.js, SvelteKit, etc.) or what is defined in vercel.json.
The result is stored in .vercel/output and is exactly what you are going to deploy.

vercel deploy --prebuilt --prod
Uploads the already built artifact to production.
With --prebuilt, Vercel does not rebuild: what you tested in CI is what your user will see.

✅ Final result

With this workflow, each merge to main runs a clean build and deploys that same artifact to production in Vercel. You get:

reproducible builds,
faster deploys,
and clear CI logs for debugging.

🐙 Prefer to configure it visually?

Writing workflows by hand gives you total control, but sometimes you want speed with built-in validations.

With OctoLab, you can set up this same pipeline visually: choose actions, fill in fields, and the YAML is generated instantly, ready to commit.

👉 Try it out: https://www.octolab.app/templates/vercel-pro-deployment

🧵 Conclusion

This workflow provides you with a clean CI → production flow on every push to main, using Vercel's recommended approach: pull → build → deploy. It's easy to adapt to previews, monorepos, or strict reproducibility (fixed Node and CLI).

Use it as a base and evolve it with caching, notifications, or environment gates as your team grows.

Publish your packages to NPM automatically with GitHub Actions

OctoLab Team — Fri, 15 Aug 2025 10:31:21 +0000

Automating publication prevents manual errors, speeds up releases, and forces you to maintain a repeatable and transparent process.

In this article, we're going to create a GitHub Actions workflow that publishes to NPM when you push to main. The flow installs dependencies, runs tests, compiles, and, if all goes well, publishes the package using a secure token stored as a secret.

🎯 What is the purpose of the workflow?

Every time you merge changes to main, we want to:

Install dependencies
Run tests
Build the package
Publish to NPM using secure credentials

This standardizes the publishing process and reduces the risk of human error.

🧬 General workflow structure

name: Publish to NPM
on:
  push:
    branches:
      - main

jobs:
  publish:
    name: publish
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test

      - name: Build package
        run: npm run build

      - name: Publish to NPM
        uses: JS-DevTools/npm-publish@v3
        with:
          token: ${{ secrets.NPM_TOKEN }}

🛠️ What does each step do?

on: push to main
Triggers the workflow when pushing to the main branch. If you prefer to publish only with tags, you can change the trigger to on: push: tags: - ‘v*’.

actions/checkout@v4
Downloads the repository to the runner.

actions/setup-node@v4
Configures Node.js (v22 in the example). You can enable cache: ‘npm’ to speed up installations.

npm ci / npm install
Installs dependencies. npm ci is faster and more reproducible in CI if you use package-lock.json.

npm run test and npm run build
Verify that the package passes tests and compiles correctly before publishing.

JS-DevTools/npm-publish@v3
Publish the package by reading package.json. Use the token you pass through with.token.

🔐 Authentication with NPM: NPM_TOKEN

To publish, you need a token in NPM and save it as a secret in GitHub:

Create an Automation Token in your NPM account (recommended for CI; respects 2FA and allows automatic publishing).
In GitHub, go to Settings → Secrets and variables → Actions → New repository secret.
Create the secret NPM_TOKEN with the value of the NPM token.

💡 If your package is scoped (e.g., @your-org/package), make sure that package.json contains “name”: “@your-org/package” and “publishConfig”: { ‘access’: “public” } if you want it to be public.

Example of publishConfig in package.json:

{
  "name": "@tu-org/tu-paquete",
  "version": "1.2.3",
  "publishConfig": {
    "access": "public",
    "tag": "latest"
  }
}

🧪 Dry-run and version control

Dry-run: test the flow without actually publishing:

- name: Publish to NPM (dry run)
  uses: JS-DevTools/npm-publish@v3
  with:
    token: ${{ secrets.NPM_TOKEN }}
    dry-run: true

Versioning: this flow publishes the version specified in package.json. Be sure to update the version before merging to main.
If you use automatic versioning (e.g., Conventional Commits + automatic releases), integrate that stage before the publication step.

✅ Final result

With this workflow:

You publish to NPM in a consistent and repeatable manner.
You avoid broken releases thanks to preliminary tests + builds.
You keep credentials secure with GitHub Secrets.
You reduce manual steps and time between merge and release.

🐙 Would you rather set it up with a visual interface?

If you're interested in defining this flow with a visual interface and getting the YAML instantly, you can use OctoLab:

Step-by-step visual editor
Dynamic fields for actions and tokens
Real-time YAML preview
Built-in validations
Copy/download and you're done

👉 Try it out: https://www.octolab.app/templates/npm-publish

🧵 Conclusion

Automating publication to NPM with GitHub Actions reduces friction and errors. With a simple configuration—tests, build, and a publish step with a secure token—you can standardize releases and focus on building value.

If this was helpful, let me know what you would like to add to the template (tags, prereleases, monorepos, changelogs, etc.). Let's keep going!

Verify your pull requests in NX monorepos with GitHub Actions

OctoLab Team — Thu, 07 Aug 2025 09:33:53 +0000

One of the great advantages of GitHub Actions is its ability to automate validation flows tailored to your project structure. And monorepos created with NX are a perfect case in point.

In this article, we will build a GitHub Actions workflow that automatically validates any pull request in an NX monorepo, running lint, tests, and compilation only on the affected projects. This allows us to speed up CI, reduce noise, and maintain code quality without wasting resources.

🎯 What is the purpose of this workflow?

We want the following actions to be performed every time a pull request is opened:

Detect which parts of the monorepo have been affected
Run lint only on those parts
Run the relevant tests
Compile the affected packages or applications

This ensures that only necessary tasks are executed and that errors are detected as soon as possible — something that is key in monorepos of a certain size.

🧬 General structure of the workflow

Below, I will show you the complete content of the workflow that we are going to analyze:

name: NX Pull request verify
on:
  pull_request: {}

jobs:
  verify:
    name: verify
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install dependencies
        run: npm install

      - name: Run lint
        run: npx nx affected --target=lint --head=HEAD --base=origin/main

      - name: Run tests
        run: npx nx affected --target=test --head=HEAD --base=origin/main

      - name: Build package
        run: npx nx affected --target=build --head=HEAD --base=origin/main

Let's now take a step-by-step look at what each section does.

🛠️ What does each step involve?

on: pull_request
This section indicates that the workflow will run every time a pull request is opened, updated, or reopened. It is the most common trigger in CI flows for collaborative teams.

uses: actions/checkout@v4
This step downloads the code from the repository so that it is available in the runner.

📌 Tip: You can configure this step to make a shallow clone or bring in specific branches, but the default configuration is usually sufficient.

uses: actions/setup-node@v4
Here we define the version of Node.js that will be used in the runner (v22 in this case). This ensures consistency between developers and CI.

Some additional useful options:

cache: ‘npm’: speeds up the installation of dependencies
check-latest: true: forces the latest available version of semver
registry-url: useful if you are going to publish packages to NPM

run: npm install
Install the project dependencies. For CI environments, it is recommended to use npm ci if you have a package-lock.json, as it is faster and more predictable.

⚙️ The specific logic of NX

The most interesting thing about this workflow is that it uses the nx affected command, which allows you to run tasks only on projects affected by the changes introduced in the pull request.

npx nx affected --target=lint
Run linter only on modified projects.

npx nx affected --target=test
Run the corresponding tests only on those projects.

npx nx affected --target=build
Only compile the packages or applications that have been affected.

This selective approach is one of the great advantages of NX, and its integration with GitHub Actions makes it especially powerful in large monorepos.

🧠 What do --head and --base mean?

These two options tell NX which branches to compare the changes against to determine what has been affected:

--base=origin/main: specifies the reference branch (e.g., main)
--head=HEAD: refers to the current commit of the PR

NX will calculate which projects have been modified between main and the HEAD of the pull request, and will only execute the necessary tasks on them.

✅ Final result: Intelligent and efficient CI

This workflow allows each pull request to go through a well-defined validation system, without the need to run unnecessary tasks across the entire repository.

Key advantages:

Saves execution time in CI
Less resource consumption
Early validation of errors in critical code
Improves the experience for external contributors

💡 Ideas for extending this workflow

Some ideas to improve it even further:

Add caching with actions/cache
Run validation on multiple versions of Node using matrix
Include automatic comments in the pull request with results
Split jobs in parallel (lint, test, build)

But we'll leave that for another article! 😉

🐙 Would you prefer a visual way to build this workflow?

If you don't want to write this YAML by hand or prefer to focus on logic rather than syntax, you can use OctoLab:

✅ Step-by-step visual editor
✅ Smart fields for NX actions
✅ Real-time YAML preview
✅ Automatic validations
✅ Copy, download, and use instantly

👉 Try it out at: https://www.octolab.app

🧵 Conclusion

Well-managed NX monorepos require efficient automation, and this workflow is an excellent way to ensure quality without wasting resources. With tools like GitHub Actions and approaches like nx affected, you can take your project's CI to the next level.

And if you want to do all this without fighting with YAML, you know where to find help 🤗.

Verify your Pull Requests with GitHub Actions in Node.js projects

OctoLab Team — Tue, 05 Aug 2025 07:16:08 +0000

One of the most common uses of GitHub Actions in Node.js projects is to automate code validation every time someone proposes a change via a pull request.

This type of validation usually involves several key steps:

Install dependencies to make sure the project can run correctly.
Running the linter, a tool that analyzes the style and quality of the code.
Run the tests that automatically verify that the project's functionality continues to work.
Build the project to check for errors before deploying or publishing.

In this article we will set up a GitHub Actions workflow that automates this whole process every time someone opens or updates a pull request. We will explain step by step what each part of the workflow does and why it is important.

🎯 The purpose of the workflow

We want that, every time a pull request is opened in our project, a set of tasks is executed to verify that the code complies with the project standards:

It installs correctly
Passes the linter tool
Passes the tests
Compiles without errors

🧬 General workflow structure

name: Node.js pull request verify

on:
  pull_request: {}

jobs:
  verify:
    name: Verify
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install dependencies
        run: npm install

      - name: Run lint
        run: npm run lint

      - name: Run tests
        run: npm run test

      - name: Build package
        run: npm run build

⚙️ What parts compose a GitHub Actions workflow?

Before going into detail, it is useful to understand how a GitHub Actions workflow is structured. The main elements are:

Trigger (on:)
Defines when the workflow is executed. It can be when pushing, opening a pull request, publishing a release, executing manually, etc.
In our case, we use pull_request, which is triggered every time a PR is created or updated.

Runner (runs-on:)
It is the operating system where the job is executed. GitHub provides hosted runners, such as ubuntu-latest, windows-latest or macos-latest, but we also have the possibility to use self-hosted runners.

Steps (steps:)
These are the actions or commands that are executed within a job. They can be:

Reusable actions such as actions/checkout or actions/setup-node.
Specific commands defined with run, such as npm install or npm test.

🪜 Step-by-step of our workflow

on: pull_request

This block indicates that the workflow will be triggered when a pull request is opened, updated or reopened in the repository. It is ideal for branch-based continuous integration flows.

uses: actions/checkout@v4

This step downloads the code from the repository so that it is available within the runtime environment.

Some additional options that this action allows are:

fetch-depth: 0 clones the entire repository history (by default only the current commit).
ref: branch-name** you can set a specific branch
path: subdirectory clone the code in a specific path

For this case, just use it without extra configuration:

- uses: actions/checkout@v4

uses: actions/setup-node@v4

This action installs a specific version of Node.js, in our case version 22. It also allows you to configure dependency caching, authentication with registries, and more.

- uses: actions/setup-node@v4
  with:
    node-version: "22"

Other useful options are:

cache: ‘npm’ enables dependency caching using actions/cache underneath
check-latest: true** forces to use the latest available version that complies with the semver.
registry-url: to configure publishing to NPM

Working scripts

- run: npm install
- run: npm run lint
- run: npm run test
- run: npm run build

These steps execute the commands defined in the project's package.json file. Their purpose is to prepare and validate the code before it goes to production:

npm install will install all the project's dependencies.
npm run lint will run the linter, which helps to detect style errors or common problems in the code.
npm run test** will run the automatic tests defined by the team.
npm run build** will generate the final package, either an app, a library or a bundle ready to deploy.

💡 If you are using package-lock.json, you can replace npm install with npm ci, which is faster and guarantees a more consistent and reproducible installation in CI environments.

✅ Final result

With this flow you guarantee that all code proposed via pull request has gone through a basic verification, without the need for manual reviews or local builds. You can integrate it with other additional steps such as:

Static analysis (Sonar, extended ESLint...).
Automatic comments on Pull Request
Deploys to staging environments
...

🐙 Do you want to avoid writing it by hand? There is a more convenient way

Understanding how a workflow works in Github Actions is indispensable. It gives you control and helps you customize everything to your needs.

✅ Without indentation errors
✅ With built-in validations
✅ Copy, paste and go.

🧠 Conclusion

This workflow is an excellent basis for quality assurance in Node.js projects. It can be easily adapted to other needs: monorepos, automatic deployments, publishing to NPM or running on multiple versions of Node.

If you prefer to use OctoLab we will be very grateful for your feedback! 🤗