CI Pipeline Setup For OpenZeppelin With Hardhat & Polkadot

Oct 19, 2025 by SLV Team 59 views

Hey guys! Let's dive into setting up a robust Continuous Integration (CI) pipeline for your OpenZeppelin projects that integrate with the Polkadot ecosystem. This is super important for ensuring your code is always in tip-top shape, especially when dealing with bleeding-edge tech like Hardhat Polkadot plugin and the Polkadot node. We'll walk through creating a GitHub CI workflow that automatically runs tests on every pull request, fetches the newest Hardhat Polkadot plugin, and grabs the latest Polkadot node for testing. Buckle up; it's gonna be a fun ride!

Why a CI Pipeline is Your Best Friend

First off, let's chat about why a CI pipeline is essential, especially in blockchain development. Think of it as your safety net and your tireless coding buddy. In the world of smart contracts and blockchain, bugs can be incredibly costly – we're talking real money here! A CI pipeline helps catch those pesky errors early in the development process, long before they make it to the main stage.

With a well-configured CI pipeline, you can automate a whole bunch of tasks. We're talking about automatically running tests, checking code style, and even deploying your contracts to a test network. This not only saves you a ton of time but also ensures consistency across your project. Plus, it's a fantastic way to enforce coding standards and best practices within your team. Everyone's code gets the same level of scrutiny, leading to a higher quality codebase overall.

In our case, setting up a CI pipeline for an OpenZeppelin project interacting with Polkadot means we need to ensure our contracts are compatible with the latest Polkadot node and that the Hardhat Polkadot plugin is playing nicely. This involves fetching the newest versions of these tools, which can be a bit of a hassle to do manually every time. Automating this process with CI is a game-changer. It guarantees that our tests always run against the most up-to-date environment, giving us confidence that our contracts will behave as expected when deployed.

So, to sum it up, a CI pipeline is not just a nice-to-have; it's a must-have for any serious blockchain project. It boosts code quality, saves time, and ultimately protects your project from costly errors. Now, let’s get our hands dirty and set up this magical pipeline!

Step-by-Step Guide to Setting Up Your CI Pipeline

Alright, let's get into the nitty-gritty of setting up your CI pipeline. We're going to create a GitHub Actions workflow that ticks all the boxes: runs tests on pull requests, fetches the latest Hardhat Polkadot plugin, and uses the most recent Polkadot node for testing. Trust me; it's easier than it sounds!

1. Create a `.github/workflows` Directory

First things first, you'll need to create a .github directory in the root of your project if it doesn't already exist. Inside .github, create another directory called workflows. This is where GitHub Actions looks for workflow files, which are essentially the blueprints for your CI pipeline.

2. Create a Workflow File

Inside the workflows directory, create a new YAML file. You can name it something descriptive like ci.yml or openzeppelin-polkadot-ci.yml. This file will define the steps and configurations for your CI pipeline.

3. Define the Workflow Trigger

At the top of your workflow file, you'll need to define when this workflow should run. In our case, we want it to run on every pull request. Here's how you can do that:

name: OpenZeppelin Polkadot CI

on:
  pull_request:
    branches:
      - main # Or your main branch name

This snippet tells GitHub Actions to trigger this workflow whenever a pull request is opened or updated against the main branch (you can adjust the branch name as needed).

4. Set Up the Jobs

Next, we'll define the jobs that make up our CI pipeline. A job is a set of steps that run on the same runner (a virtual environment). We'll create a single job called build that encompasses all our tasks:

jobs:
  build:
    runs-on: ubuntu-latest # Or your preferred runner
    steps:
      # Steps will go here

We're using ubuntu-latest as our runner, which is a common choice for Node.js projects. You can also use other runners like macos-latest or windows-latest if your project requires them.

5. Add Steps to the Job

Now comes the fun part: adding the steps that our job will execute. We'll need steps for:

Checking out the code
Setting up Node.js
Installing dependencies
Fetching the latest Hardhat Polkadot plugin
Fetching the latest Polkadot node
Running tests

Here’s how it looks in YAML:

 steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16' # Or your preferred Node.js version

      - name: Install dependencies
        run: npm install

      - name: Fetch latest Hardhat Polkadot plugin
        run: npm install --save-dev @chainsafe/hardhat-polkadot

      - name: Fetch latest Polkadot node
        run: | #This step assumes you have a way to fetch the Polkadot node. It might involve downloading a binary or using a package manager. If you need to specify a specific version, replace 'latest' with the version number.
          # Example: wget https://example.com/polkadot-latest.tar.gz && tar -xvzf polkadot-latest.tar.gz
          echo "Fetching Polkadot node..."
          # Add the command to download and set up the Polkadot node here
          # For example: You might want to download the polkadot binary from a specific URL
          #  and then set it up in the environment.

      - name: Run tests
        run: npx hardhat test

Let's break this down:

actions/checkout@v3: This action checks out your code into the runner environment.
actions/setup-node@v3: This action sets up Node.js. We're using version 16 here, but you can adjust it to your project's needs.
npm install: This command installs your project's dependencies.
npm install --save-dev @chainsafe/hardhat-polkadot: This command fetches the latest version of the Hardhat Polkadot plugin.
The "Fetch latest Polkadot node" step is a placeholder. You'll need to replace the comment with the actual commands to download and set up the Polkadot node. This might involve downloading a binary or using a package manager. You might want to download the polkadot binary from a specific URL and then set it up in the environment.
npx hardhat test: This command runs your Hardhat tests.

6. Commit and Push

That's it! Save your workflow file, commit it to your repository, and push it to GitHub. The next time you open a pull request, GitHub Actions will automatically trigger your CI pipeline.

Diving Deeper: Customizing Your CI Pipeline

Now that you've got the basics down, let's talk about how you can customize your CI pipeline to fit your project's specific needs. The beauty of GitHub Actions is its flexibility; you can tweak almost every aspect of it. Let's explore a few common customizations.

1. Running Tests on Specific Branches

In our basic setup, we configured the workflow to run on pull requests against the main branch. But what if you want to run tests on other branches as well? No problem! You can easily modify the on section of your workflow file to include additional branches:

on:
  pull_request:
    branches:
      - main
      - develop # Add the 'develop' branch

With this change, the workflow will now run on pull requests targeting either the main or develop branch. You can add as many branches as you need, making your CI pipeline super versatile.

2. Using Environment Variables

Sometimes, you might need to pass sensitive information or configuration values to your tests. Environment variables are the perfect way to do this. You can define environment variables in your workflow file and then access them in your test scripts.

First, let's define an environment variable in the workflow file:

jobs:
  build:
    runs-on:
    ubuntu-latest
    env:
      POLKADOT_NODE_URL: "ws://localhost:9944" # Example Polkadot node URL
    steps:
      # Steps will go here

Here, we've defined an environment variable called POLKADOT_NODE_URL and set its value to an example Polkadot node URL. Now, you can access this variable in your test scripts using Node.js's process.env:

const polkadotNodeUrl = process.env.POLKADOT_NODE_URL;
console.log(`Using Polkadot node URL: ${polkadotNodeUrl}`);

This allows you to configure your tests without hardcoding sensitive information directly into your code.

3. Caching Dependencies

Installing dependencies every time a workflow runs can be time-consuming. Fortunately, GitHub Actions provides a caching mechanism that can speed things up significantly. You can cache your project's node_modules directory, so the next workflow run can reuse the installed packages instead of reinstalling them.

Here's how you can add a caching step to your workflow:

steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: ~/.npm # npm cache files are stored in ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys:
            ${{ runner.os }}-node-

      - name: Install dependencies
        run: npm install

Let's break this down:

actions/cache@v3: This action provides the caching functionality.
path: This specifies the path to cache. In this case, we're caching the npm cache directory.
key: This is a unique key for the cache. It includes the runner's operating system and a hash of the package-lock.json file. If the package-lock.json file hasn't changed, the cache will be hit.
restore-keys: These are fallback keys to use if the primary key doesn't match. This allows you to reuse a previous cache even if the package-lock.json file has changed.

With this caching step in place, your CI pipeline will run much faster, especially for projects with many dependencies.

4. Running Specific Tests

Sometimes, you might want to run only a subset of your tests in the CI pipeline. This can be useful if you have a large test suite and want to focus on the tests that are most relevant to the changes in a pull request. The Hardhat testing framework provides options for running specific tests or test suites.

For example, you can use the grep option to run tests that match a specific pattern:

- name: Run specific tests
  run: npx hardhat test --grep "MyContract" # Runs tests that include "MyContract" in their description or file name

This command will run only the tests that have "MyContract" in their description or file name. You can adjust the grep pattern to match your specific needs.

5. Notifying on Test Failures

It's crucial to know when your tests fail in the CI pipeline. GitHub Actions provides several ways to notify you of test failures, such as sending email notifications or posting messages to a Slack channel. You can use third-party GitHub Actions to integrate with various notification services.

For example, you can use the slack-github-action to post a message to a Slack channel when a workflow fails:

- name: Slack Notification on Failure
  if: failure()
  uses: slackapi/slack-github-action@v1.23.0
  with:
    slack-user-oauth-token: ${{ secrets.SLACK_USER_OAUTH_TOKEN }}
    slack-channel: '#your-slack-channel'
    github-token: ${{ secrets.GITHUB_TOKEN }}
    status_context: