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:
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:
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 Type | Purpose | On Push |
|---|---|---|
GENERAL | Any Git content | Index + webhooks |
SCRIPT_PROJECT | Script source files | Detects changed scripts, syncs source to scripting engine |
DOCUMENTATION | Documentation content | Index + webhooks |
ANALYTIC_QUERY_PROJECT | Analytic query definitions | Detects 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:
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.
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:
- Updates repository disk size
- Dispatches webhook events (push, branch created/deleted, tag created/deleted)
- Extracts WorkOps task keys from commit messages (pattern
[A-Z][A-Z0-9_]+-\d+) and stores references - Enqueues search index jobs (repository metadata + file content)
- Triggers CI/CD pipelines for updated branches
- Dispatches content change events for
SCRIPT_PROJECTrepos
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: