Tenderly is now the simulation company for onchain operations. Model every onchain move. Read the announcement →

Simple CI Setup With Virtual Environments & GitHub Actions

Simplify your CI setup by using a GitHub Action to provision a new Virtual TestNet synced with mainnet data. Then, automate deployments and run your Hardhat tests to accelerate your development and testing cycle.

How to set up a CI pipeline with Hardhat and Virtual TestNets using GitHub Actions

In this post

Virtual Environments are fully synced replicas of production chains that replace both local nodes and public testnets. Designed to fit any stage of the development workflow, Virtual Environments can integrate into your CI pipeline and existing frameworks, opening new testing capabilities while saving you significant resources.

With a simple GitHub Action, you can set up your CI infrastructure on Virtual Environments integrated with Hardhat. This way, you can automate deployments, test end-to-end integrations across chains, and speed up the entire CI process.

Why use Virtual Environments in CI

Integrating Virtual Environments into your CI pipeline gives you zero-setup, development and testing infrastructure for automating smart contract deployments and testing code changes. You can even test end-to-end integrations by staging your smart contracts, frontend, and backend components on a Virtual Environment.

Using Virtual Environments in your CI pipeline eliminates the overhead of local node and public testnet management for your team. You can simplify the entire CI setup with a GitHub Action that automatically provisions a brand-new Virtual Environment synced with mainnet data. 

This way, you can set up a fast, reproducible CI pipeline for your Hardhat tests, enabling:

  • Complex testing use cases: Virtual Environments sync with the latest mainnet state, providing up-to-date on-chain data in real time. With complete mainnet data, you can test real-world integrations with oracles, LP providers, exchanges, and indexers, validating complex DeFi interactions under realistic conditions.
  • Fast, automated deployments: Virtual Environments enable near-instant deployments and transaction execution. Instead of writing extensive scripts, you can focus on your CI workflow file while a GitHub Action provisions a new Virtual Environment per PR. You can then automate deployments for each code push and run unit, smoke, or integration tests for every change commit or pull request.
  • SUDO mode over environment state: Using Tenderly’s custom RPC methods, you get full control over your environment to test custom scenarios. For instance, you can increase the block number or time to test governance proposals, manipulate storage to override on-chain values, and even revert states between different test runs.
  • Get unlimited test assets: Virtual Environments come with an unlimited faucet for native and ERC-20 tokens that you can use through the Dashboard or with custom RPC methods. Aside from topping up any wallet, you can set custom token balances for specific accounts or contracts. 
  • Privacy during early development: With Virtual Environments, you can deploy and verify your contracts privately during early development. This way, you don’t have to use local nodes that limit your testing capabilities or deploy to public testnets that reveal your code publicly before it’s ready.
  • Efficient debugging and collaboration: Whenever a test fails, open a Virtual Environment with a built-in private explorer and debugging tools to troubleshoot a bug. Inspect a failed transaction with the most detailed stack and error trace, jumping to a revert on the exact line of code. Even share a link directly to the revert with your team to fix the issue and then commit code changes to test them out.

How to set up a CI pipeline on Virtual Environments with GitHub Actions

The easiest way to set up your CI infrastructure on Virtual Environments is to use a GitHub Action that automatically provisions a new Virtual Environment for your CI runs. Use this GitHub Action to integrate Virtual Environments with Hardhat and set up an efficient CI pipeline for automated testing.

To set up your CI pipeline, you need to complete a few simple steps: 

  1. Create a GitHub workflow file 
  2. Include and configure the @tenderly/vnet-github-action
  3. Set up steps to test your Hardhat project 
  4. Connect Hardhat to Virtual Environments

To get started, take a look at this sample GitHub workflow setup:

name: Hardhat Pipeline
on: [push, pull_request]
env:
  DEBUG: '@tenderly/github-action'
  ## Needed available as env variables for Hardhat.config.js
  TENDERLY_PROJECT_NAME: ${{ vars.TENDERLY_PROJECT_NAME }}
  TENDERLY_ACCOUNT_NAME: ${{ vars.TENDERLY_ACCOUNT_NAME }}
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - name: Setup Virtual Environment
        uses: Tenderly/vnet-github-action@v1.0.6
        with:
          access_key: ${{ secrets.TENDERLY_ACCESS_KEY }}
          project_name: ${{ vars.TENDERLY_PROJECT_NAME }}
          account_name: ${{ vars.TENDERLY_ACCOUNT_NAME }}
          testnet_name: "Staging environment"
          network_id: 1
          chain_id: 1
          state_sync: true
          public_explorer: true
          verification_visibility: bytecode
 
      - name: Install dependencies
        run: npm install
 
      - name: Run Tests
        run: npm run test:vnet
        working-directory: examples/Hardhat-ignition
 
      - name: Deploy Contracts
        run: npm run deploy:vnet
        working-directory: examples/Hardhat-ignition

After the step “Setup Virtual Environment” completes, the RPC link will be in the environment variable TENDERLY_ADMIN_RPC_URL that you need to reference from your hardhat.config.ts.

Once you run your tests and the action finishes, the Tenderly/vnet-github-action will pause the Virtual Environment, turning off the RPC automatically. While you cannot further run tests on this Virtual Environment, all your transaction data is available for inspection and analysis, allowing you to identify any potential bugs. 

If any of your Hardhat tests fail, you can find the failed transaction in the dev-friendly Tenderly Dashboard. Virtual TestNets come with a built-in private explorer and debugging tools, enabling you to troubleshoot the issue as soon as a test fails.

ℹ️
For more detailed setup information, follow this step-by-step documentation guide.

Automate CI testing on zero-setup simulated networks

Replace resource-consuming infrastructure management with zero-setup Virtual Environments. Virtual Environments integrate seamlessly with your existing frameworks, bringing automated deployments and near-instant execution to your development and testing workflows.

By using GitHub Actions for Virtual Environment CI infrastructure, you can quickly set up mainnet-based replicas for CI testing and automate the entire process while getting full on-chain data. To get started, try forking a chain within milliseconds!