> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in Git server

> Host your repositories on the RBS platform with branch-based servers, access control, and seamless build integration

# Built-in Git server

RBS includes an integrated Git server so you can host your code on the same platform that builds, tests, and deploys it. No separate Git hosting service required.

## Why use the built-in Git server?

* **Zero-config CI**: pushes automatically trigger builds on the branch server.
* **Branch = server**: every active branch gets a dedicated build environment.
* **Faster clones**: your code is already on the platform — no network round-trip to clone.
* **Unified access control**: one set of permissions for code, builds, and deployments.

<Tip>You can also import repositories from GitHub, GitLab, or Bitbucket if you prefer an external Git host. RBS mirrors the repository and keeps it in sync.</Tip>

## Getting started

### Create a repository

From the [RBS Dashboard](https://app.rbs.dev):

1. Click **New Project → Create new repository**.
2. Name your repository and choose visibility (public or private).
3. Click **Create**.

### Clone and push

```bash theme={null}
# Clone the repository
git clone https://git.rbs.dev/your-org/your-repo.git
cd your-repo

# Create your project files
echo 'config_setting(key = "project_name", value = "my-app")' > WORKSPACE.rbs

# Push
git add -A
git commit -m "Initial commit"
git push origin main
```

### Import an existing repository

```bash theme={null}
# From the dashboard, choose "Import repository" and provide the URL
# Or use the CLI:
rbs project import --url https://github.com/your-org/your-repo.git
```

RBS clones the external repository and sets up a mirror. You can push to either the RBS remote or the original remote — changes are synchronized.

## Branch-based servers

Every active branch in your repository can have a dedicated RBS server. The server starts automatically when:

* A developer connects to the branch from their editor.
* A push is made to the branch (for CI).
* A scheduled workflow runs on the branch.

### Branch lifecycle

| Event                         | Server state                                   |
| ----------------------------- | ---------------------------------------------- |
| First push to new branch      | Server created, repo cloned, workers deployed. |
| Developer connects via editor | Server starts (if not running).                |
| Push to branch                | CI workers execute workflows.                  |
| All users disconnect          | Server idles (configurable auto-shutdown).     |
| Branch merged or deleted      | Server decommissioned, resources cleaned up.   |

### Working with branches

```bash theme={null}
# Create and push a new branch
git checkout -b feature/user-auth
git push origin feature/user-auth
# → RBS creates a new server for this branch

# Switch branches in your editor
# → Your editor reconnects to the correct branch server

# Delete a branch
git push origin --delete feature/user-auth
# → RBS decommissions the branch server
```

## Authentication

### SSH keys

```bash theme={null}
# Add your SSH key in the dashboard under Settings → SSH Keys
# Then clone with SSH:
git clone git@git.rbs.dev:your-org/your-repo.git
```

### HTTPS with tokens

```bash theme={null}
# Generate a personal access token in the dashboard
git clone https://your-token@git.rbs.dev/your-org/your-repo.git

# Or configure Git credential helper
git config credential.helper store
```

## Access control

Manage who can access your repositories:

| Role           | Read code | Write code | Manage settings | Manage members |
| -------------- | --------- | ---------- | --------------- | -------------- |
| **Viewer**     | ✅         | ❌          | ❌               | ❌              |
| **Developer**  | ✅         | ✅          | ❌               | ❌              |
| **Maintainer** | ✅         | ✅          | ✅               | ❌              |
| **Admin**      | ✅         | ✅          | ✅               | ✅              |

### Branch protection

Protect important branches from direct pushes:

```
Settings → Branches → Branch protection rules

main:
  ✅ Require pull request reviews (1 approval)
  ✅ Require all CI checks to pass
  ✅ Prevent force pushes
  ✅ Require agents to approve (optional)
```

## Webhooks

Configure webhooks to notify external services:

| Event              | Description                            |
| ------------------ | -------------------------------------- |
| `push`             | Code pushed to any branch.             |
| `pull_request`     | PR opened, updated, merged, or closed. |
| `build:completed`  | A build finished (success or failure). |
| `test:completed`   | Tests finished running.                |
| `deploy:completed` | A deployment finished.                 |

```
Settings → Webhooks → Add webhook

URL: https://your-service.com/hooks/rbs
Secret: ********
Events: push, pull_request, build:completed
```

## Mirroring external repositories

If you host code on GitHub, GitLab, or Bitbucket, you can set up bidirectional mirroring:

1. Go to **Settings → Mirrors**.
2. Add the external repository URL.
3. Configure sync direction:
   * **Pull mirror**: RBS pulls from the external repo (read-only import).
   * **Push mirror**: RBS pushes changes to the external repo.
   * **Bidirectional**: Changes sync both ways.

```bash theme={null}
# Example: mirror from GitHub
rbs project mirror --url https://github.com/your-org/repo.git --direction bidirectional
```

## Git LFS support

Large files are supported via Git LFS:

```bash theme={null}
# Track large files
git lfs track "*.bin" "*.model" "datasets/**"

# Push as usual — LFS files are stored on the RBS platform
git add .gitattributes
git commit -m "Track large files with LFS"
git push
```

LFS objects are stored on the RBS platform and accessible to all branch servers without additional downloads.