Lesson 10: CI/CD for Forta Bots (Automating Tests & Deployments)

In previous lessons, you have learned how to craft detection logic, run bots locally, and operate your own scan node. Today, we move to a key DevOps practice: CI/CD. Continuous Integration and Continuous Deployment ensure your bots are tested, stable, and automatically updated across environments whenever you push changes.

Understanding CI/CD makes you a stronger Forta Administrator and security engineer.

---

Why CI/CD is important for Forta Agents

When building Forta agents, it's not just about writing detection logic, it's also about making sure your bots are reliable, maintainable, and safe to update. This is where CI/CD pipelines (Continuous Integration and Continuous Deployment) become relevant.

Firstly, having automated tests helps catch problems before they ever reach the blockchain. You avoid the risk of deploying a bot that crashes or fails to detect what it should. The earlier you catch issues, the safer your monitoring stack becomes.

CI/CD also guarantees consistency. The same exact version of your bot can be run in development, staging, or production with no surprises.

Another key benefit is speed. Once your pipeline is set up, every commit you push to GitHub can trigger automatic tests and deployment. This means faster feedback, faster iteration, and less downtime when improving your detection logic.

Lastly, it creates a clear history of every change. Who pushed it, what changed, when it was deployed, it's all tracked. That kind of transparency is critical for security audits, team coordination, and long-term maintainability.

CI/CD transforms your Forta bot repo into a production-ready pipeline.

---

Example Workflow Overview

1. Developer pushes code to GitHub

2. CI pipeline triggers: runs tests (npm test), lint, build

3. If everything passes, merge to main branch

4. Deployment pipeline builds Docker image or publishes agent

5. Scan node automatically picks up new agent version

---

GitHub Actions Setup

Assuming your bot is in a GitHub repo:

1. Create .github/workflows/ci.yml in your repo:

name: Forta Agent CI

on:
  push:
    branches:
      - main
      - 'feat/**'
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
    - name: Install Dependencies
      run: npm ci
    - name: Run Tests
      run: npm test
    - name: Lint
      run: npm run lint || echo "No linter configured"
    - name: Package Forta Bot
      run: forta agent package
    - name: Upload Artifact
      uses: actions/upload-artifact@v3
      with:
        name: forta-agent
        path: agent.zip

2. Add package script to package.json:

"scripts": {
  "test": "node test/agent.spec.js",
  "package": "forta agent package --output agent.zip"
}

3. Add optional linter:

"scripts": {
  "lint": "eslint ."
},
"devDependencies": {
  "eslint": "^8.0.0"
}

4. Configure your scan node to auto-deploy on agent update, or manually upload the new agent.zip via Forta CLI

---

Option: Build & Push Docker Image

If your environment requires containerization:

1. Add Dockerfile:

FROM node:16
WORKDIR /usr/src/app
COPY . .
RUN npm ci
RUN npm run package
CMD ["forta", "agent", "run"]

2. In CI pipeline, build and publish:

- name: Build image
  run: docker build -t yourorg/forta-bot:${{ github.sha }} .
- name: Push image
  uses: docker/login-action@v2
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- name: Update Deployment
  run: |
    ssh deploy@your-server "docker pull yourorg/forta-bot:${{ github.sha }} && docker restart forta-bot-service"

---

Testing & Quality Measurements

• Use unit tests to simulate edge cases

• Use coverage tools to ensure enough detection logic paths are tested

• In case of CI failure, merge is blocked

---

Best Practices That Save Time

• Pin your Node.js version. Make sure everyone (or your CI server) uses the same Node version to avoid “it works for me” bugs.

• Don’t log secrets in CI. If you log your private keys or RPC URLs in GitHub Actions or any CI pipeline, they might leak publicly. Always use environment variables or GitHub Secrets.

• Automate changelogs. Tools like standard-version help generate a changelog based on your commit messages, saving time and keeping history organized.

• Tag your releases. Tagging (like v1.0.2) in Git lets you see exactly what code was deployed, which is useful for rollback or debugging.

---

Key Concepts Recap

• CI/CD ensures bots are reliable, repeatable, and easy to maintain

• Automated tests catch errors before deployment

• Packaging agents with forta agent package simplifies deployment

• Together, Docker and GitHub Actions handle everything you need to safely deliver updates to your bot

• Proper automation reduces your operational load and increases trust in your system

In the next lesson, we will see integration testing on mainnet and testnets, and how to run fuzz tests against your bots.

Until next meditation,
The Blockchain Security Monk