Alchemy CI Integration

Overview

CI/CD pipeline for Alchemy-powered dApps with Hardhat mainnet fork testing, Sepolia deployment, and contract verification.

Prerequisites

• A repository secret store containing a least-privilege Alchemy test key and, where deployment is authorized, a testnet-only deployer credential.
• A pinned Hardhat, Solidity, and fork block configuration that has passed locally with synthetic or public-chain fixtures.
• Branch protection that limits testnet deployment to an approved protected branch and preserves the workflow run as a release receipt.

Instructions

Step 1: GitHub Actions Workflow

# .github/workflows/web3-ci.yml
name: Web3 CI

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - name: Run Hardhat tests with Alchemy fork
        env:
          ALCHEMY_API_KEY: ${{ secrets.ALCHEMY_API_KEY }}
        run: npx hardhat test
      - name: Check API key not in build
        run: |
          npm run build
          if grep -r "${{ secrets.ALCHEMY_API_KEY }}" dist/ 2>/dev/null; then
            echo "FAIL: API key found in build output!"
            exit 1
          fi

  deploy-testnet:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - name: Deploy to Sepolia
        env:
          ALCHEMY_API_KEY: ${{ secrets.ALCHEMY_API_KEY }}
          DEPLOYER_PRIVATE_KEY: ${{ secrets.DEPLOYER_PRIVATE_KEY }}
        run: npx hardhat run scripts/deploy.ts --network sepolia

Step 2: Fork Test Configuration

// hardhat.config.ts — CI-optimized
const config = {
  solidity: '0.8.24',
  networks: {
    hardhat: {
      forking: {
        url: `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`,
        blockNumber: 19000000,  // Pinned for reproducible CI
        enabled: !!process.env.ALCHEMY_API_KEY,
      },
    },
  },
  mocha: {
    timeout: 60000,  // Fork tests are slower
  },
};

Output

• GitHub Actions with fork-based tests and testnet deployment
• API key exposure scanning in build output
• Pinned block number for reproducible CI results

Examples

Open a pull request that changes a contract test and let the test job run with the fork key supplied only through the CI secret context. The expected result is a passing pinned-block fork test, type check, and build scan with no key material in artifacts or logs. On merge to the protected branch, require the separate testnet deployment job to use the scoped testnet credential and save the transaction hash as the receipt. If a fork test cannot authenticate, a secret scan detects a value, or the deploy step is not explicitly authorized, stop the pipeline and rotate or correct the configuration before retrying.

Error Handling

Failure	Response
Fork request is rate-limited or unauthorized	Fail the job without exposing the key; verify the secret and account limits.
Test diverges from pinned fork state	Update the fixture deliberately and record the new approved block number.
Build scan finds secret material	Revoke the affected credential, remove it from outputs, and rerun from a clean artifact.
Testnet deployment fails	Preserve the transaction/error receipt and do not promote the change to a production deployment.

Resources

• Alchemy Docs
• Hardhat Testing

Next Steps

For deployment procedures, see alchemy-deploy-integration.