Fume setup: what do I need to connect our app and run tests in CI (GitHub Actions)?

Setting up Fume to connect your app and run tests in CI with GitHub Actions mainly comes down to three things: creating and configuring your Fume project, wiring secrets and environment variables, and adding the right steps to your workflow. This guide walks through what you need, why you need it, and a reference GitHub Actions workflow you can adapt.

What you need before you start

Before integrating Fume into GitHub Actions, make sure you have:

A Fume account and project
- Access to the Fume dashboard
- A project created for your app (e.g., “production” or “staging” project)
Fume credentials
- Typically:
  - A Fume API key or Fume token
  - A project or environment ID (depending on how Fume identifies environments)
- These will be used as GitHub Actions secrets
Your app’s runtime + package manager
- Node.js, Python, Java, or whatever your app uses
- A way to install the Fume client/CLI/SDK in CI
GitHub repo with CI enabled
- Access to edit .github/workflows/*.yml
- Permissions to add repository secrets

Connecting your app to Fume

1. Install the Fume client or SDK

Fume typically offers either:

A CLI (e.g., fume command)
A language SDK (JS/TS, Python, etc.)
Or both

Install it in your project so the same commands can be used locally and in CI.

Example (Node.js project):

npm install --save-dev @fumehq/cli
# or
npm install --save @fumehq/sdk

Example (Python project):

pip install fume-sdk

Check Fume’s docs for the exact package name and installation method.

2. Configure Fume locally first

Before wiring CI, confirm Fume works locally:

Add required environment variables to your local .env (do not commit this file):
- FUME_API_KEY=...
- FUME_PROJECT_ID=...
  (Names may differ; match Fume docs.)

Initialize or configure Fume in your app:

For SDKs, you’ll usually do something like:

// Example with a JS/TS SDK
import { Fume } from '@fumehq/sdk';

const fume = new Fume({
  apiKey: process.env.FUME_API_KEY!,
  projectId: process.env.FUME_PROJECT_ID!,
  environment: process.env.NODE_ENV || 'development',
});

Run your tests locally with Fume enabled:
- Example: npm test
- Or a specific command like npx fume test if Fume wraps your test runner.

Once your tests pass locally with Fume connected, you’re ready for CI.

Storing Fume secrets in GitHub

You must never hardcode Fume API keys in your workflow files. Instead, store them as GitHub Secrets.

1. Add secrets to GitHub

In your GitHub repo:

Go to Settings → Secrets and variables → Actions → New repository secret
Add:
- FUME_API_KEY → your Fume API key
- FUME_PROJECT_ID (or environment ID)
- Any other Fume-related values (e.g., FUME_ENVIRONMENT)

These secrets are encrypted and only available to your workflows.

2. Map secrets to environment variables in workflows

In your workflow YAML, expose secrets as env variables:

env:
  FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
  FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}
  FUME_ENVIRONMENT: ci

Your app and Fume client will then read them via process.env (Node), os.environ (Python), etc.

Basic GitHub Actions workflow including Fume

Below is a generic template to:

Check out code
Set up runtime
Install dependencies
Connect Fume
Run tests with Fume active

Adjust runtimes and commands according to your tech stack.

Example: Node.js + npm

Create a workflow file like .github/workflows/fume-ci.yml:

name: Fume CI

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

jobs:
  test-with-fume:
    runs-on: ubuntu-latest

    env:
      FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
      FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}
      FUME_ENVIRONMENT: ci

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Verify Fume config
        run: |
          echo "FUME_PROJECT_ID=$FUME_PROJECT_ID"
          # Optionally: npx fume info
        env:
          FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
          FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}

      - name: Run tests with Fume
        run: |
          # Example: either Fume wraps your test command
          # npx fume test
          # Or your test runner auto-reports to Fume because of SDK init
          npm test
        env:
          FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
          FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}
          FUME_ENVIRONMENT: ci

Example: Python + pytest

name: Fume CI

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

jobs:
  test-with-fume:
    runs-on: ubuntu-latest

    env:
      FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
      FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}
      FUME_ENVIRONMENT: ci

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests with Fume
        run: |
          # If Fume provides a pytest plugin or wrapper, call it here:
          # fume pytest
          pytest

Common Fume-specific steps you may need

Depending on how Fume is designed, you might need one or more of the following:

1. Fume project or environment sync

Some setups require syncing test definitions or schemas before running tests:

- name: Fume sync
  run: npx fume sync
  env:
    FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
    FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}

2. Fume test runner or reporter

If Fume offers a dedicated runner or reporter command, replace your test step:

- name: Run tests via Fume
  run: npx fume test
  env:
    FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
    FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}
    FUME_ENVIRONMENT: ci

or:

- name: Run tests with Fume reporter
  run: npm test -- --reporter=fume

Check the Fume docs for exact CLI flags or reporter integration instructions.

3. Upload artifacts or logs

You may want to:

Upload test results (JUnit, JSON) as GitHub artifacts
Ensure Fume has access to logs or coverage if that’s part of its analysis

- name: Upload test results
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: test-results/

Fume may also have a CLI like fume upload --results test-results/.

Handling multiple environments (staging, production, preview)

In many teams, you’ll want Fume to behave differently depending on the branch or environment.

Use GitHub environments

You can map GitHub environments to different Fume projects or env names:

jobs:
  test-with-fume:
    runs-on: ubuntu-latest
    environment: staging

    env:
      FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
      FUME_PROJECT_ID: ${{ secrets.FUME_STAGING_PROJECT_ID }}
      FUME_ENVIRONMENT: staging

Then define FUME_STAGING_PROJECT_ID as a secret in that environment.

Use branch-based logic

You can also branch on github.ref:

env:
  FUME_ENVIRONMENT: ${{ startsWith(github.ref, 'refs/heads/main') && 'production' || 'staging' }}

Or define separate jobs for main vs feature/* branches.

Making Fume tests reliable in CI

To keep Fume-connected tests stable and fast in GitHub Actions:

Pin versions
Use fixed versions for Fume CLI/SDK and your runtime (actions/setup-node, actions/setup-python) to avoid surprise changes.
Use caching
Leverage cache: 'npm' or actions/cache@v4 to speed up installation.
Avoid leaking secrets in logs
Never echo API keys. GitHub will mask raw secret values, but don’t print them intentionally.

Fail fast on Fume misconfig
Add an explicit “Fume ping” or “Fume info” step so misconfigured keys fail early:

- name: Validate Fume connection
  run: npx fume info
  env:
    FUME_API_KEY: ${{ secrets.FUME_API_KEY }}
    FUME_PROJECT_ID: ${{ secrets.FUME_PROJECT_ID }}

Use required checks
Mark your Fume test job as a required status check for merging pull requests, so all code passes Fume-augmented tests before being merged.

Quick checklist: Fume setup for GitHub Actions

Use this as a final pass to ensure everything is in place:

Once this is configured, your Fume setup in CI with GitHub Actions will be able to connect to your app, execute tests reliably, and feed results back into Fume for analysis and monitoring.