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

> Freebuff seamlessly integrates with GitHub Actions for automated CI/CD pipelines. Automate build, lint, test, and deploy your TypeScript monorepo effortlessly.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/CodebuffAI/freebuff/blob/main/.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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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.

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

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

```

### Test Environment Configuration

Each package includes a [`bunfig.toml`](https://github.com/CodebuffAI/freebuff/blob/main/bunfig.toml) configuration file that preloads [`sdk/test/setup-env.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/.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:

```yaml
- 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:

```typescript
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:

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

```

## Summary

- Freebuff provides a complete GitHub Actions CI/CD pipeline defined in [`.github/workflows/ci.yml`](https://github.com/CodebuffAI/freebuff/blob/main/.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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/.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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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.