Component configuration defines buildable and deployable units stored in components/<id>.json.

Schema

{
  "id": "string",
  "name": "string",
  "local_path": "string",
  "remote_path": "string",
  "build_artifact": "string",
  "build_command": "string",
  "extract_command": "string",
  "version_targets": [
    {
      "file": "string",
      "pattern": "string"
    }
  ],
  "changelog_target": "string",
  "extensions": {},
  "release": {}
}

Fields

Required Fields

• id (string): Unique component identifier, derived from local_path directory name (lowercased)
• local_path (string): Absolute path to local source / git checkout directory, ~ is expanded
• remote_path (string): Remote path relative to project base_path (the deploy target)
• build_artifact (string): Build artifact path relative to local_path, must include filename
• build_command (string): Shell command to execute in local_path during builds

Important: local_path must point to a git repository / source checkout, not the production deploy target. The deploy target is derived from project.base_path + component.remote_path. If local_path points to the deployed directory, builds will run inside production and uncommitted-changes checks will fail (the directory isn’t a git repo). This is a common misconfiguration after server migrations.

Optional Fields

• name (string): Human-readable component name, defaults to id
• extract_command (string): Command to execute after artifact upload, runs inside target directory
  • Supports template variables: {artifact}, {targetDir}
• version_targets (array): List of version detection patterns
  • file (string): Path to file containing version (relative to local_path)
  • pattern (string): Regex pattern to extract version (first capture group)
• changelog_target (string): Path to changelog file (relative to local_path)
• extensions (object): Extension-specific settings
  • Keys are extension IDs (e.g., "wordpress", "rust")
  • Values are extension setting objects
• release (object): Component-scoped release configuration
  • enabled (boolean): Whether release pipeline is enabled
  • steps (array): Release step definitions
  • settings (object): Release pipeline settings

Hook Fields

• Supports template variables: {artifact}, {targetDir}

local_path vs remote_path

local_path (source)                          remote_path (deploy target)
┌──────────────────────────┐                ┌──────────────────────────────────────────┐
│ ~/repos/extrachill-api/  │  ── build ──▶  │ /var/www/site/wp-content/plugins/        │
│ (git checkout, builds    │    deploy      │ extrachill-api/                          │
│  run here)               │                │ (project.base_path + remote_path)        │
└──────────────────────────┘                └──────────────────────────────────────────┘

• file (string): Path to file containing version (relative to local_path)
• pattern (string): Regex pattern to extract version (first capture group)

Important: local_path must point to a git repository / source checkout, not the production deploy target. The deploy target is derived from project.base_path + component.remote_path. If local_path points to the deployed directory, builds will run inside production and uncommitted-changes checks will fail (the directory isn’t a git repo). This is a common misconfiguration after server migrations.

Example

{
  "id": "extrachill-api",
  "name": "Extra Chill API",
  "local_path": "/Users/dev/extrachill-api",
  "remote_path": "wp-content/plugins/extrachill-api",
  "build_artifact": "build/extrachill-api.zip",
  "build_command": "npm run build",
  "extract_command": "unzip -o {{artifact}} && rm {{artifact}}",
  "version_targets": [
    {
      "file": "composer.json",
      "pattern": ""version":\s*"([^"]+)""
    }
  ],
  "changelog_target": "CHANGELOG.md",
  "pre_version_bump_commands": [
    "cargo build --release"
  ],
  "post_version_bump_commands": [
    "git add Cargo.lock"
  ],
  "post_release_commands": [
    "echo 'Release complete!'"
  ],
  "extensions": {
    "wordpress": {
      "settings": {
        "php_version": "8.1"
      }
    }
  },
  "release": {
    "enabled": true,
    "steps": [
      {
        "id": "test",
        "type": "extension.run",
        "label": "Run Tests",
        "config": {
          "extension": "rust"
        }
      }
    ]
  }
}

Version Target Format

Important: local_path must point to a git repository / source checkout, not the production deploy target. The deploy target is derived from project.base_path + component.remote_path. If local_path points to the deployed directory, builds will run inside production and uncommitted-changes checks will fail (the directory isn’t a git repo). This is a common misconfiguration after server migrations.

pre_version_bump_commands (array of strings): Commands to run BEFORE version targets are updated

• Keys are extension IDs (e.g., "wordpress", "rust")
• Values are extension setting objects

Extract Command Context

post_version_bump_commands (array of strings): Commands to run AFTER version files are updated

• enabled (boolean): Whether release pipeline is enabled
• steps (array): Release step definitions
• settings (object): Release pipeline settings

post_release_commands (array of strings): Commands to run after the release pipeline completes

• Supports template variables: {artifact}, {targetDir}

Storage Location

Setting local_path to the same directory as the deploy target is a misconfiguration — builds would run in production and homeboy deploy would fail uncommitted-changes checks.

• file (string): Path to file containing version (relative to local_path)
• pattern (string): Regex pattern to extract version (first capture group)

Related

• Keys are extension IDs (e.g., "wordpress", "rust")
• Values are extension setting objects