Does Freebuff Support CI/CD Pipelines? Complete GitHub Actions Integration Guide

Yes, Freebuff ships with a production-ready CI/CD pipeline powered by GitHub Actions that automates building, linting, testing, and deployment across the TypeScript monorepo.

Freebuff is an open-source AI coding assistant organized as a monorepo containing packages like cli, sdk, and agents. The project includes comprehensive continuous integration support out of the box, enabling automated quality assurance and release management through a sophisticated GitHub Actions workflow defined in .github/workflows/ci.yml.

GitHub Actions CI/CD Pipeline Architecture

The continuous integration workflow orchestrates the entire development lifecycle from code commit to artifact generation. It leverages Bun as the package manager and runtime, providing fast dependency installation and execution across all workspace packages.

Workflow Triggers and Environment Setup

The pipeline activates automatically on three distinct events: push, pull_request, and a nightly schedule. This multi-trigger approach ensures that every code change undergoes validation before merging while also catching regressions through scheduled runs.

The environment setup phase checks out the repository, installs the Bun package manager, executes bun install to fetch dependencies, and caches the node_modules folder between runs to optimize performance. This caching strategy significantly reduces build times for subsequent commits.

Build, Lint, and Type-Check Stages

Quality assurance begins with compilation. The workflow runs bun run build, which compiles TypeScript source files across all monorepo packages including the CLI, SDK, and agent modules.

Following the build, two critical validation steps execute:

1. ESLint via bun lint to enforce code style and catch potential errors
2. TypeScript type-checking via bun run typecheck to ensure type safety before any code reaches production

These steps run sequentially to fail fast on quality issues before proceeding to expensive test execution.

Testing with Guard Scripts

A distinguishing feature of Freebuff's CI pipeline is the test guard mechanism implemented in scripts/ci/test-with-guard.ts. This wrapper script executes before the actual test suite to verify that all expected test files are present. If any test suite is missing—indicating a broken configuration or incomplete test setup—the script aborts the job immediately rather than reporting a false-positive success.

Tests execute via bun test within each package directory (cd <package> && bun test) to respect package-local .env handling and configuration isolation. This approach ensures that environment variables specific to individual packages are loaded correctly during test execution.

Coverage Reporting and Artifact Generation

After successful test completion, the workflow generates coverage reports using bun run coverage and uploads these as artifacts. This enables developers to inspect code coverage trends over time and identify untested critical paths before they reach production.

Optional Deployment Automation

The pipeline includes a separate release job that triggers exclusively on tagged commits. This job reuses build artifacts from the CI run to publish both CLI binaries and npm packages, ensuring that exactly the same code validated during CI reaches production environments.

CI-Aware Runtime Configuration

Freebuff's runtime code adapts its behavior when executing inside automated environments through environment detection mechanisms.

Environment Variable Detection

The file common/src/env.ts exports an IS_CI boolean flag derived from process.env.CI. When this flag evaluates to true, the application disables interactive UI features such as user prompts that would block indefinitely in non-interactive CI runners.

import { IS_CI } from '@codebuff/common/env';

if (IS_CI) {
  // Skip interactive prompts
  await runNonInteractiveMode();
}

Test Environment Configuration

Each package includes a bunfig.toml configuration file that preloads sdk/test/setup-env.ts before executing tests. This setup provides deterministic placeholder values for required environment variables, ensuring that tests run consistently in CI environments without exposing sensitive production credentials.

Extending the CI/CD Pipeline

Developers can customize the existing workflow by modifying .github/workflows/ci.yml to include additional security scans, custom validations, or deployment steps.

Adding Security Audits

To integrate npm audit into the pipeline, insert the following step after the test execution phase:

- name: Security audit
  run: |
    bun install --silent
    npm audit --audit-level=high

Conditionally Executing CI-Only Logic

Use the IS_CI flag to execute code exclusively during pipeline runs, such as generating API documentation:

import { IS_CI } from '@codebuff/common/env';

if (IS_CI) {
  await generateApiDocs(); // Writes documentation to ./docs/api
}

Running the Test Guard Locally

Developers can execute the same test validation logic used in CI on their local machines to ensure consistency:

bun run scripts/ci/test-with-guard.ts

Summary

• Freebuff provides a complete GitHub Actions CI/CD pipeline defined in .github/workflows/ci.yml that triggers on pushes, pull requests, and scheduled runs
• The workflow uses Bun for dependency management (bun install), building (bun run build), linting (bun lint), and testing (bun test) across the monorepo
• A test guard script at scripts/ci/test-with-guard.ts prevents false-positive builds by verifying test suite existence before execution
• Runtime code detects CI environments through common/src/env.ts, which exports an IS_CI flag to disable blocking interactive features
• Optional automated releases trigger on tagged commits to publish CLI binaries and npm packages using cached build artifacts

Frequently Asked Questions

Does Freebuff support self-hosted CI/CD runners?

Yes. While the default configuration uses GitHub-hosted runners, the workflow is compatible with self-hosted infrastructure. You can modify the runs-on field in .github/workflows/ci.yml to target your own runners, provided they have Bun installed and support the standard GitHub Actions environment.

What package manager does Freebuff use in its CI/CD pipeline?

Freebuff uses Bun exclusively for all CI operations. The workflow installs Bun during the setup phase and uses bun install for dependencies, bun run build for compilation, and bun test for test execution. This provides consistent, high-performance package management across local development and automated environments.

How does Freebuff handle environment variables during CI testing?

Each package contains a bunfig.toml that preloads test setup files to inject placeholder environment variables, ensuring deterministic test execution without requiring production secrets. Additionally, common/src/env.ts detects when process.env.CI is set and exports IS_CI=true, allowing application code to bypass interactive prompts that would block automation.

Can I disable the test guard for faster local development?

Yes. While CI uses scripts/ci/test-with-guard.ts to prevent missing test suites from passing silently, you can run bun test directly in individual package directories during local development. The guard script is specifically designed for automated environments where configuration drift could otherwise result in false-green builds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}