Bit CI

Bit's bit ci commands (plus one BVM enhancement) wrap several routine Bit tasks into single-purpose scripts so your CI pipelines stay short, readable and consistent.

bit ci verify

When to run

• Every commit that is not part of an open Pull Request (e.g. a pre-push hook).
• As an early CI job to fail fast on dependency drift or broken builds.

Exit behaviour

The command stops at the first failing step (status, then build) and returns a non-zero exit code.

bit ci pr

Export a lane to Bit Cloud whenever a Pull Request is opened or updated.

bit ci pr [--message <string>] [--build] [--lane <string>]

Internal flow (fail-fast on any step)

1. Resolve lane name

   • From --lane or current Git branch.
   • If the lane doesn’t exist remotely, create it; otherwise, bit lane checkout <lane>.

2. Run wrapped Bit commands

   bashCopy

   bit install
   bit status --strict
   bit lane create <lane>      # no-op if already exists
   bit snap --message "<msg>" --build
   bit export
   

3. Clean-up

   bashCopy

   bit lane switch main   # leaves .bitmap unchanged in the working tree
   

Typical CI placement

Run on the pull-request event after tests but before any deploy step.

bit ci merge

Publishes new semantic versions after a PR merges to main.

bit ci merge [--message <string>] [--build] [--increment <level>] [--patch|--minor|--major] [--increment-by <number>]

Automatic Version Bump Detection

When no explicit version flags are provided, bit ci merge can automatically determine the version bump level from the commit message:

1. Explicit Keywords (highest priority):

   • BIT-BUMP-MAJOR anywhere in commit message → major version bump
   • BIT-BUMP-MINOR anywhere in commit message → minor version bump

2. Conventional Commits (when enabled):

   • feat!: or BREAKING CHANGE → major version bump
   • feat: → minor version bump
   • fix: → patch version bump

3. Default: patch version bump

Note: Auto-detection only occurs when no version flags (--patch, --minor, --major, etc.) are provided. Explicit flags always take precedence.

Internal flow

1. Ensure main lane

   bashCopy

   bit lane switch main   # preserves working tree files
   

2. Tag, build, export

   bashCopy

   bit install
   bit tag --message "<msg>" --build --persist   # --persist only if soft tags exist
   bit export
   

3. Archive remote lane (house-keeping).

4. Commit lock-file updates

   bashCopy

   git add .bitmap pnpm-lock.yaml
   git commit -m "chore(release): sync bitmap + lockfile"
   

Version bump examples

# Explicit version bump (takes precedence over auto-detection)
bit ci merge --minor --message "feat: add new API endpoint"
bit ci merge --major --message "feat!: breaking API changes"
bit ci merge --patch --increment-by 3 --message "fix: critical patches"

# Automatic detection from commit message (no flags needed)
git commit -m "feat: add new API endpoint"
bit ci merge --build  # → auto-detects minor bump

git commit -m "feat!: breaking API changes"
bit ci merge --build  # → auto-detects major bump

git commit -m "fix: resolve memory leak"
bit ci merge --build  # → auto-detects patch bump (if conventional commits enabled)

# Using explicit keywords for auto-detection
git commit -m "feat: add new feature BIT-BUMP-MINOR"
bit ci merge --build  # → auto-detects minor bump

git commit -m "refactor: major code restructure BIT-BUMP-MAJOR"
bit ci merge --build  # → auto-detects major bump

# Default patch increment (when no detection rules match)
git commit -m "chore: update dependencies"
bit ci merge --build  # → defaults to patch bump

# Prerelease increment (explicit flag required)
bit ci merge --pre-release dev --message "feat: experimental feature"

CI hint

Gate this step behind a branch-protection rule so only fast-forward merges trigger a release.

Configuration

The CI aspect supports configuration in workspace.jsonc:

{
  "teambit.git/ci": {
    "commitMessageScript": "node scripts/generate-commit-message.js",
    "useConventionalCommitsForVersionBump": true,
    "useExplicitBumpKeywords": true
  }
}

commitMessageScript

Optional. Path to a script that generates custom commit messages for the bit ci merge command.

• Default: Uses "chore: update .bitmap and lockfiles as needed [skip ci]"
• Usage: The script should output the desired commit message to stdout
• Security: Commands are parsed to avoid shell injection - no chaining allowed
• Working Directory: Script runs in the workspace root directory

Example script:

#!/usr/bin/env node
const { execSync } = require('child_process');

try {
  const version = execSync('npm show @my/package version', { encoding: 'utf8' }).trim();
  console.log(`bump version to ${version} [skip ci]`);
} catch {
  console.log('chore: update .bitmap and lockfiles as needed [skip ci]');
}

useConventionalCommitsForVersionBump

Optional. Enable automatic version bump detection based on conventional commit patterns.

• Default: false (disabled)
• When enabled: Analyzes commit messages for conventional commit patterns:
  • feat!: or BREAKING CHANGE → major version bump
  • feat: → minor version bump
  • fix: → patch version bump

{
  "teambit.git/ci": {
    "useConventionalCommitsForVersionBump": true
  }
}

useExplicitBumpKeywords

Optional. Enable automatic version bump detection using explicit keywords.

• Default: true (enabled)
• Keywords:
  • BIT-BUMP-MAJOR anywhere in commit message → major version bump
  • BIT-BUMP-MINOR anywhere in commit message → minor version bump

{
  "teambit.git/ci": {
    "useExplicitBumpKeywords": false // disable explicit keywords
  }
}

Example usage:

git commit -m "feat: add new feature BIT-BUMP-MINOR"
bit ci merge --build  # → automatically uses minor version bump