# Gittan — Agent Guide

Gittan is a git hosting platform with gated pipelines and no pull requests.
Add this file to your project's CLAUDE.md (or equivalent) so AI coding agents
understand how gittan works and can help you effectively.

## Core model

```
Organization → Team → Repository
```

- **Organization**: top-level entity with a display name and slug (used in URLs).
- **Team**: unit of ownership. Every repo belongs to exactly one team.
- **Repository**: belongs to a team. Push directly to main.

No personal namespaces. No forks. No feature branches in normal workflow.

## No pull requests — gated commits

There are no PRs. Every push to main runs a pipeline:
- **Pass** → push lands, code is deployed.
- **Fail** → push is rejected, nothing changes on main.

Pipeline output streams directly to the terminal during `git push`.
This is the primary feedback loop — not a web UI.

```
$ git push
remote: ── pipeline starting ──────────────────
remote:   fix: resolve auth token refresh race
remote: ⟳ install
remote: ✓ install              8s
remote: ⟳ typecheck, lint, test, build
remote: ✓ typecheck            12s
remote: ✓ lint                 13s
remote: ✓ test                 18s
remote: ✓ build                15s
remote: ⟳ publish
remote: ✓ publish              22s
remote: ── pipeline passed ─── 45s ───────────
remote: ✓ main → a1b2c3d
```

**What this means for agents:**
- Don't create feature branches or PRs.
- Commit to main and push. The pipeline is the gate.
- If the push fails, read the pipeline output to diagnose.
- Fix the issue and push again.

## Permissions

| Role | Access |
|---|---|
| Org member | Read all repos in the org |
| Team member | Full admin on the team's repos (push, settings, secrets) |
| Org owner | Manage org: members, teams, billing, policies, secrets |

You're on the team (full access) or you're not (read-only).

## Git URLs

```
SSH:   git@git.gittan.eu:{org-slug}/{repo}.git
HTTPS: https://git.gittan.eu/{org-slug}/{repo}.git
```

## Authentication

No passwords. OIDC only.

- `gittan auth login` — device flow, opens browser
- Credentials stored at `~/.config/gittan/credentials` (auto-refreshed)
- Git credential helper: `git config --global credential.https://git.gittan.eu.helper 'gittan credential'`

For SSH: add keys via the web UI (Settings → SSH Keys).

## CLI

Install: `curl -fsSL https://cli.gittan.eu/install.sh | bash`

Key commands:
- `gittan auth login|logout|status` — authentication
- `gittan teams list|create` — manage teams
- `gittan repos list|create` — manage repositories
- `gittan pipelines list|logs` — view pipeline runs
- `gittan secrets set|list|delete <scope>` — manage secrets (org/team/repo)
- `gittan deploy status` — deployment status
- `gittan status` — connectivity and auth check

Global flags: `--org <id>`, `--format json|pretty|table`, `--token <token>`.

Output is JSON by default.

## Pipeline configuration

Pipelines are automatic — gittan detects project type and runs appropriate steps.

Optional: customize via `.gittan.yaml` in the repo root:

```yaml
steps:
  install:
    runs-on: ubuntu-latest
    steps:
      - run: pnpm install --frozen-lockfile

  test:
    needs: [install]
    steps:
      - run: pnpm test

  build:
    needs: [install]
    steps:
      - run: pnpm build

  deploy:
    needs: [test, build]
    gate: main
    steps:
      - run: pnpm deploy:prod
```

Key concepts:
- Steps run as a DAG (directed acyclic graph) based on `needs`.
- `gate: main` — step only runs on pushes to main.
- Org-level policies can inject mandatory steps (security scanning, etc.) that teams cannot bypass.

## Secrets

Three scopes — narrower overrides broader:

| Scope | Visible to |
|---|---|
| Org | All pipelines in the org |
| Team | That team's pipelines |
| Repo | That repo's pipelines only |

Names must be UPPER_SNAKE_CASE. Injected as environment variables in pipeline steps.

```bash
gittan secrets set repo --name DATABASE_URL --value "postgres://..."
gittan secrets list team
```

## Hostnames

| Host | Purpose |
|---|---|
| gittan.eu | Web UI + API |
| auth.gittan.eu | OIDC authentication |
| git.gittan.eu | Git operations (SSH + HTTPS) |
| images.gittan.eu | Container registry |
| cli.gittan.eu | CLI binary downloads |

## Common agent tasks

### Pushing code changes

```bash
git add <files>
git commit -m "feat: description of change"
git push
# Read pipeline output — if it fails, fix and push again
```

### Checking pipeline status

```bash
gittan pipelines list --format pretty
gittan pipelines logs <pipeline-id>
```

### Creating a new repo

```bash
gittan repos create --name my-service --team <team-id>
git clone git@git.gittan.eu:{org-slug}/my-service.git
```

### Managing secrets

```bash
gittan secrets set repo --name API_KEY --value "sk-..."
gittan secrets list repo
gittan secrets delete repo --name OLD_SECRET
```

## Things to avoid

- **Don't create branches or PRs** — gittan uses trunk-based development with gated commits.
- **Don't use GitHub/GitLab-specific features** — gittan is its own platform.
- **Don't hardcode secrets** — use `gittan secrets` to manage them.
- **Don't ignore pipeline failures** — a failed push means the code didn't land. Read the output and fix it.
- **Don't reference `origin` without checking** — the repo might have multiple remotes. Verify with `git remote -v`.