BoscaDeveloper Documentation

Bosca Git

Host repositories, manage pull requests, and connect versioned source files to scripts and analytics queries.

Overview

Bosca Git serves the Git smart HTTP protocol using JGit. Pack files live in S3-compatible object storage; refs and pack metadata live in PostgreSQL. The dedicated Git server handles clone, fetch, and push requests, while the platform API exposes repository management through GraphQL.

Git Protocol

Standard Git operations work out of the box:

bash

Private repositories require authentication and repository permissions. Scoped API tokens use git:read for reads and git:write for writes. For a signed-in CLI account, bosca git clone provisions a Git credential and configures the Bosca credential helper:

bash

Create the repository in Studio first and use its displayed clone URL in place of the example. The CLI requires Git on your PATH. Later plain git push and git fetch operations use the configured credential helper.

Repository Content Types

Repositories are classified by content type, which enables specialized post-push behaviors:

Content TypePurposeOn Push
GENERALAny Git contentIndex + webhooks
SCRIPT_PROJECTScript source filesDetects changed scripts, syncs source to scripting engine
DOCUMENTATIONDocumentation contentIndex + webhooks
ANALYTIC_QUERY_PROJECTAnalytic query definitionsDetects changed queries, syncs to analytics engine

Source Refs — Scripts & Queries from Git

Git serves as the source of truth for scripts and analytics queries. A source ref links a script or query to a specific file in a Git repository:

Link a script to a Git file

Supply an existing script ID and repository ID, a file path such as scripts/example/source.bosca.kts, and a full ref such as refs/heads/main. With the runner's Git listeners enabled, pushes enqueue source-sync jobs. They find linked files changed on the selected ref, read the blobs from Git, and update the stored script source and version.

The same flow works for analytics queries via setQuerySourceRef — SQL files stored in Git are synced to the analytics query store on push.

This means you can version-control your scripts and queries in Git, review changes via pull requests, and update linked platform source when the selected ref changes. Keep the runner and Git listeners running for synchronization.

Pull Requests & Reviews

Bosca Git has a full pull request system:

  • Create PRs — specify source/target branches, title, description, assignees
  • Reviews — approve, request changes, or comment with inline review comments on specific files/lines
  • Merge strategies — merge commit, squash, or rebase (configurable per-repository)
  • Auto-delete branches — configurable via repository settings

Branch Protection

Enforce rules on protected branches:

  • Block force pushes
  • Block branch deletion
  • Require pull requests — direct pushes are rejected; changes must go through a PR
  • Push access restrictions — limit who can push to the branch

Push Hooks

Pre-receive

Enforces branch protection rules before refs are updated. Rejects pushes that violate protection policies.

Post-receive

After a successful push:

  1. Updates repository disk size
  2. Dispatches webhook events (push, branch created/deleted, tag created/deleted)
  3. Extracts WorkOps task keys from commit messages (pattern [A-Z][A-Z0-9_]+-\d+) and stores references
  4. Enqueues search index jobs (repository metadata + file content)
  5. Triggers CI/CD pipelines for updated branches
  6. Dispatches content change events for SCRIPT_PROJECT repos

CI/CD Pipelines

Bosca Git includes a built-in CI/CD system:

  • Pipeline definitions parsed from YAML files in the repository
  • Trigger types: push, pull request, tag, manual, schedule
  • Agent modes: runner (executes jobs) and orchestrator (manages ephemeral VMs)
  • Concurrency groups to prevent conflicting runs
  • Per-repository secrets (encrypted at rest)
  • Step-level logs with streaming via the CLI (bosca ci run logs --step-id STEP_UUID --run-id RUN_UUID --follow)

Webhooks

Webhooks deliver push, PR, and pipeline events to external URLs with HMAC-SHA256 signatures. Failed deliveries retry with exponential backoff (10s, 60s, 300s). Delivery history is queryable via GraphQL.

Storage Architecture

Repository data is split between two backends:

  • Object data (packs, LFS objects) — streamed to and from S3-compatible object storage.
  • Refs and pack metadata — kept in PostgreSQL so any server pod can resolve refs without local disk.

Git server instances use the shared database and object storage rather than a local repository directory. Keep those backing services available and use matching authentication and storage configuration across instances.

GraphQL API

The full Git API is available via GraphQL:

graphql