Tenderly Virtual TestNets CI/CD Infrastructure

The Tenderly/vnet-github-action automates provisioning of multiple parallel Virtual TestNets for smart contract CI/CD pipelines. You can fork multiple networks simultaneously (e.g., Ethereum Mainnet, Base, Arbitrum), with each Virtual TestNet providing:

• State Sync with mainnet giving you access to the latest mainnet state even after forking
• Unlimited Faucet allowing you to fund your test accounts with native and ERC-20 balances
• Debugger helping you analyze and debug transactions and smart contracts
• Public Block Explorer with configurable verification visibility of your smart contracts

Features

• Multi-Network Testing: Fork multiple networks in parallel with unique chain IDs
• Automated Deployments: Deploy and verify contracts with complete deployment logs
• CI/CD Integration: Run tests against forked networks and maintain staging environments
• Artifact Collection: Track deployments across networks with structured logs

Operating Modes

The action supports two modes:

• CI Mode: Creates ephemeral Virtual TestNets that are cleaned up after testing. No artifacts or build info files are persisted nor pushed after the run.
• CD Mode:
  • Creates persistent Virtual TestNets for staging environments
  • Collects deployment artifacts in the .tenderly/ directory
  • Optionally commits and pushes artifacts to your repository (controlled by parameter push_on_complete)

Quick Start

1. Prerequisites

1. Get your Tenderly access key and store it in GitHub Action Secrets as TENDERLY_ACCESS_KEY
2. Set up your project name and account name in GitHub Action variables as TENDERLY_PROJECT_NAME and TENDERLY_ACCOUNT_NAME

2. Basic Configuration

Create .github/workflows/ci.yaml:

name: Smart Contract CI
on: [ push, pull_request ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Virtual TestNet
        uses: Tenderly/vnet-github-action@v1.0.x
        with:
          mode: CI
          access_key: ${{ secrets.TENDERLY_ACCESS_KEY }}
          project_name: ${{ vars.TENDERLY_PROJECT_NAME }}
          account_name: ${{ vars.TENDERLY_ACCOUNT_NAME }}
          testnet_name: 'CI Test Network'
          network_id: |
            1
            8453
          chain_id_prefix: 7357  # Results in chain IDs 73571, 73578453
          public_explorer: true
          verification_visibility: 'src'
          state_sync: true
          push_on_complete: true

Examples

Explore hardhat-ignition and foundry CI setup in more detail. For more details, explore the CI with hardhat and CI with Foundry guides.

Configuration Options

Required Inputs

Name	Description
access_key	Tenderly API Access Key
project_name	Tenderly Project Name
account_name	Tenderly Account Name
testnet_name	Display name for the Virtual TestNet
network_id	Network IDs to fork (multiline input)
block_number	Block number to fork from
chain_id_prefix	Prefix for generating unique chain IDs. Use "" for no prefix.

Optional Inputs

Name	Default	Description
public_explorer	false	Enable block explorer
verification_visibility	'bytecode'	Contract verification visbility ('abi', 'src', or 'bytecode')
state_sync	false	Enable State Sync
mode	'CI'	Action mode ('CI' or 'CD') - CI cleans up after completion, CD preserves the Virtual TestNet
push_on_complete	false	Push deployment artifacts in CD mode

Environment Variables

Network-Specific Variables

After forking each of the specified networks, the following environment variables are exported (replace {network_id} with actual network ID).

Variable	Description
TENDERLY_TESTNET_ID_{network_id}	Virtual TestNet UUID, uniquely identifying it within Tenderly
TENDERLY_ADMIN_RPC_URL_{network_id}	Admin RPC endpoint with cheatcode methods
TENDERLY_PUBLIC_RPC_URL_{network_id}	Public RPC endpoint
TENDERLY_CHAIN_ID_{network_id}	Chain ID
TENDERLY_TESTNET_SLUG_{network_id}	Unique TestNet slug
TENDERLY_FOUNDRY_VERIFICATION_URL_{network_id}	Foundry verification URL
BUILD_OUTPUT_FILE_{network_id}	Build output file path

For example, if you're provisioning Virtual TestNets for Ethereum Mainnet (network ID 1) and Base (network ID 8453), you'll get the public RPC by accessing $TENDERLY_PUBLIC_RPC_URL_1.

Global Variables

The following global variables are useful for configuring Hardhat verification and performing Foundry verification.

Variable	Description
TENDERLY_ACCOUNT_NAME	Tenderly account name
TENDERLY_PROJECT_NAME	Tenderly project name
TENDERLY_ACCESS_KEY	Tenderly access key
BUILD_SLUG	Unique slug for the current run of the Github Action, consisting of run number and run ID

Deployment Artifacts

Infrastructure Tracking

After each Virtual TestNet creation, the .tenderly/infra directory will hold JSON files with access information to those TestNets. The action will push this directory to your repository for CD-mode, if push_on_complete is true.

Foundry Deployment Artifacts

In CD mode, the action generates and pushes the following artifacts in the .tenderly/ directory:

• infra/{job-identifier}.json: Infrastructure information
• tmp/{testnet-slug}.json: Raw build output
• deployed-{testnet-slug}.json: Structured deployment information

Hardhat Ignition Artifacts

Hardhat ignition artifacts are present in the ignition/deployments directory and will be pushed to the main repository.

Best practices

Debug Logging

Enable debug logs by setting:

env:
  DEBUG: '@tenderly/github-action'

GitHub Environment Setup

Use GitHub CLI to set up required variables and secrets:

gh variable set TENDERLY_PROJECT_NAME --body "${TENDERLY_PROJECT_NAME}"
gh variable set TENDERLY_ACCOUNT_NAME --body "${TENDERLY_ACCOUNT_NAME}"
gh variable set DEPLOYER_WALLET_ADDRESS --body "${TENDERLY_PROJECT_NAME}"

gh secret set TENDERLY_ACCESS_KEY --body "${TENDERLY_ACCESS_KEY}"
gh secret set DEPLOYER_PRIVATE_KEY --body "${TENDERLY_PROJECT_NAME}"

Recommendations

1. Use unique chain IDs (e.g., with chain_id_prefix) to prevent transaction replay attacks
2. Enable public_explorer and set verification_visibility to 'src' for more debugging information
3. In CD mode, use push_on_complete to maintain deployment history
4. Structure your workflow to use CI mode for tests and CD mode for staging environments
5. For Foundry deployments with forge script, make sure to use the --slow flag to ensure verification succeeds

License

Tenderly