Workflow: dev → main via PR

Every llamaclaw sub-repo follows the same branch convention.

Default branch: dev

When you clone a repo, you land on dev:

git clone git@github.com:llamaclaw/esml.git
cd esml
git branch --show-current   # → dev

  • dev is where active work happens.

  • main is the stable pointer; only updated via PR.

  • CI runs on every push to dev AND every PR to main.

Making a change

git clone git@github.com:llamaclaw/<repo>.git
cd <repo>

# edit, commit
git add ...
git commit -m "fix: ..."
git push               # triggers CI on llamaclaw/<repo>

No branch-per-feature ceremony by default — all commits go to dev. For larger changes, a PR from a feature branch into dev is welcome.

Releasing

When dev is ready to go stable:

gh pr create --base main --head dev --title "Release vX.Y.Z"
# review, CodeRabbit commentary, merge

Or across the whole ecosystem at once via the umbrella:

cd llamaclaw
./scripts/release.sh 0.3.0            # opens PRs on all submodules
# ... merge each PR ...
./scripts/release.sh 0.3.0 --tag      # tags v0.3.0 on each + umbrella

Branch protection

Private repos on Free tier don’t support branch protection rules or rulesets — those require GitHub Pro. For now:

  • Convention: land in dev; PRs to main get CodeRabbit + human review

  • CI: runs on every push (no way to bypass)

  • Secrets scan: org-level gitleaks on every push + weekly

Once we go public (or upgrade to Pro), we’ll lock main with:

  • Require PR before merging

  • Require ≥1 approving review

  • Require status checks to pass (CI, gitleaks)

  • Prohibit force-pushes

  • Prohibit deletion

CodeRabbit

All sub-repos have .coderabbit.yaml with the chill profile. Install the CodeRabbit GitHub App once at org level — it’ll auto-review every non-draft PR across all repos.

Preferences (in every .coderabbit.yaml):

  • request_changes_workflow: false — CodeRabbit suggests, doesn’t block.

  • drafts: false — WIP PRs aren’t spammed with reviews.

  • gitleaks: enabled — parallel secrets check alongside our org workflow.

  • ast-grep: essential_rules — language-specific structural linting.

Submodule workflow (umbrella repo)

The umbrella pins each sub-repo at a specific commit. To bump all submodules to their latest dev tip:

cd llamaclaw
./scripts/update-all.sh
# edits + commits an atomic bump commit
git push

To bump a single submodule:

cd llamaclaw
git submodule update --remote esml
git add esml
git commit -m "bump: esml → <new sha>"
git push

Dependabot

Org-wide config at llamaclaw/.github/.github/dependabot.yml:

  • Weekly: github-actions, pip, gomod, cargo (Mondays)

  • Monthly: docker (digests)

  • Grouped PRs to minimize noise

  • Labels: dependencies, python / rust / go / etc.

Sub-repos inherit this config. To override, add a local .github/dependabot.yml in that repo.

Issue + PR templates

Org-wide defaults at llamaclaw/.github/.github/:

  • ISSUE_TEMPLATE/bug_report.yml — structured bug report

  • ISSUE_TEMPLATE/feature_request.yml — structured feature ask

  • PULL_REQUEST_TEMPLATE.md — PR description + verification checklist

Sub-repos inherit unless they ship their own.

Secrets scanning

  • Per-repo: .gitleaks.toml allowlist for known false positives (BibTeX keys, dataset IDs, scraped third-party content).

  • Org-wide: llamaclaw/.github/.github/workflows/secrets-scan.yml runs gitleaks on every push and weekly on Mondays.

GitHub’s native secret-scanning push-protection is Pro-only on private repos. Our gitleaks CI covers the same ground for free.