Automated builds with GitHub and Depot

How builds work

A changed push to your selected branch queues a job when builds and push triggers are enabled. Manual runs are also supported. GitHub Actions dispatches your workflow, then a GitHub-hosted or Depot runner checks out the exact OrbitGit commit, runs commands, and uploads verified artifacts.

Commands run on your provider, with usage billed to your GitHub or Depot account. The generated workflow targets Ubuntu and installs Bun; add language setup steps for other toolchains.

1. Save configuration with builds disabled

1. Save a GitHub token in Account settings with repository access and Actions write permission.
2. Choose a GitHub workflow repository. A private OrbitGit project requires a private workflow repository.
3. Open Builds → Configure builds. Set the runner, GitHub owner/repository, workflow filename/branch, OrbitGit source branch, commands, artifact glob, and timeout.
4. Save with Enable builds unchecked so you can install the workflow first.

{
  "enabled": false,
  "onPush": true,
  "provider": "github",
  "githubOwner": "your-user",
  "githubRepo": "private-workflows",
  "workflow": "orbitgit-build.yml",
  "workflowRef": "main",
  "branch": "main",
  "command": "bun install --frozen-lockfile\nbun test\nbun run build",
  "artifacts": "dist/*",
  "docker": false,
  "dockerfile": "Dockerfile",
  "dockerContext": ".",
  "depotProject": "",
  "timeoutMinutes": 30
}

2. Install the workflow and enable builds

1. Download workflow from Builds or use the CLI below.
2. Commit it to .github/workflows/orbitgit-build.yml in the chosen GitHub repository. It must exist on the default branch and your selected workflowRef branch.
3. Keep the generated workflow_dispatch inputs, run name, id-token: write permission, and OrbitGit helper steps; they bind authentication to your run.
4. Return to Builds, enable and save, then choose Run build now.

orbitgit build config --file build.json --repo your-user/my-app
orbitgit build workflow --out orbitgit-build.yml --repo your-user/my-app
# Commit the YAML to the GitHub workflow repository.
# Set enabled to true in build.json, then save again.
orbitgit build config --file build.json --repo your-user/my-app
orbitgit build run --repo your-user/my-app

Changes to runner provider or timeout require downloading and reinstalling the workflow. Commands and artifact selection load from the saved run configuration.

3. Optional: Depot and Docker

For Depot runners, connect your GitHub organization in Depot and install its GitHub App for the workflow repository. Depot setup needs appropriate organization owner access. Choose Depot Ubuntu in Builds; the generated label is depot-ubuntu-24.04.

For Docker, enable Also build an OCI Docker image and set Dockerfile and context. Leave Depot project empty for runner BuildKit, or enter a Depot project ID and configure that project’s GitHub Actions OIDC trust relationship. Docker acceleration works with either runner provider.

The generated step exports a Linux/amd64 OCI image as orbitgit-image.tar. It does not push to a registry. Add an authenticated registry publishing step if required.

4. Review and publish artifacts

Jobs upload a private release draft with verified output and a build report. Follow Release draft in build history, inspect its artifacts, and publish it explicitly. Enable release sharing to distribute downloads.

Paths must stay inside the checkout and filenames must be distinct. Up to 19 output files plus the report are supported, each at most 512 MiB. The Docker image counts as an output. Archive directories before selecting them.

The job credential reads that run’s source and uploads its draft. It cannot push refs, read the vault, publish, or enable sharing. Add required build secrets in your GitHub workflow; OrbitGit vault values are not automatically exported.

Monitor and troubleshoot

Use Provider logs for command output. Refresh status reconciles runs stopped outside the callback path. Cancel / revoke immediately removes OrbitGit access and requests provider cancellation.

Missing workflow: check filename, branch, and default-branch installation. Waiting for runner: check Depot integration and label. No artifacts: check the output glob and build commands.

If dispatch outcome is unknown, check GitHub before starting another run. Configuration changes invalidate active job credentials; cancel existing jobs before changing their settings.

orbitgit build status
orbitgit build refresh RUN_ID
orbitgit build cancel RUN_ID