https://github.com/flyingrobots/git-stargate
Git-Stargate: Forbidden git-fu harnessing a tiny wormhole to run pre/post-receive hooks on custom refs before mirroring to GitHub. Kiss my SaaS! 🌌🔧
https://github.com/flyingrobots/git-stargate
Last synced: about 1 month ago
JSON representation
Git-Stargate: Forbidden git-fu harnessing a tiny wormhole to run pre/post-receive hooks on custom refs before mirroring to GitHub. Kiss my SaaS! 🌌🔧
- Host: GitHub
- URL: https://github.com/flyingrobots/git-stargate
- Owner: flyingrobots
- License: mit
- Created: 2025-11-25T13:01:23.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-25T14:12:26.000Z (7 months ago)
- Last Synced: 2025-11-28T19:51:37.507Z (7 months ago)
- Language: Shell
- Size: 6.84 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Git-Stargate
Git-Stargate is a lightweight gateway for Git refs that *aren't* normal branches (e.g., `refs/_blog/*`, `refs/kv/*`, `refs/_shiplog/*`). It enforces fast-forward-only updates, requires signed commits, and can mirror accepted updates to your main remote (GitHub, GitLab, etc.). Perfect for ledger-style content, git-native CMS, and append-only logs.
### Features
- **FF-only**: Rejects non-fast-forward pushes on chosen namespaces.
- **Signed-only**: Requires `git verify-commit` to pass for new tips.
- **Mirroring**: Post-receive hook can push accepted refs to an upstream (optionally under `refs/heads/_mirror/...`).
- **Namespace-targeted**: Default `refs/_blog/*`, configurable.
- **Tiny footprint**: Bash hooks; no daemon needed. Works with bare repos over SSH.
## Quick start
```bash
# In your bare gateway repo (or let bootstrap create it)
./scripts/bootstrap.sh /srv/git/stargate.git
# Optionally set upstream for mirroring
GIT_DIR=/srv/git/stargate.git git remote add origin git@github.com:you/yourrepo.git
```
## CLI (planned)
- `git stargate init /path/to/bare`
- `git stargate set-origin `
- `git stargate ns add refs/_blog/*`
## Config (planned)
- Env or `.stargate/config` for namespaces, mirroring target, signed-only toggle, heads-mirroring flag.
## Hooks
- `pre-receive`: FF-only + signed-only for configured namespaces.
- `post-receive`: Mirrors accepted refs to upstream.
## Why not GitHub branch protection?
Branch protection only covers `refs/heads/*`. If your ledger lives under custom refs, Git-Stargate enforces policy before anything hits GitHub. When GitHub visibility is needed, mirror to `refs/heads/_blog/*`.
## Roadmap
- Small Go CLI for nicer UX.
- Tests for hooks (bats or Go integration).
- Configurable namespace list and mirror mappings.
- Optional heads-mirroring switch.
## License
[MIT](./LICENSE)
_© James Ross • [flyingrobots](http://github.com/flyingrobots)_
## Sequence: push path with stargate
```mermaid
sequenceDiagram
participant Dev as Dev workstation
participant SG as Stargate (bare repo)
participant GH as GitHub (mirror)
Dev->>SG: git push stargate refs/_blog/articles/
SG-->>SG: pre-receive: FF check + verify-commit
alt passes policy
SG-->>GH: post-receive mirror refs/_blog/* (or heads/_blog/*)
GH-->>Dev: mirror ack (non-blocking)
SG-->>Dev: push success
else fails policy
SG-->>Dev: reject push (non-FF or unsigned)
end
```
## Sequence: publish (fast-forward only)
```mermaid
sequenceDiagram
participant Dev as Dev
participant SG as Stargate
participant GH as GitHub
Dev->>Dev: update refs/_blog/published/ (FF in local repo)
Dev->>SG: git push stargate refs/_blog/published/
SG-->>SG: pre-receive policy (FF + signed)
SG-->>GH: mirror published ref
GH-->>CI: build hook fetches published refs
CI-->>Site: rebuild static JSON (writing.json)
```
## Why this exists
- Enforce FF-only and signed commits on non-branch namespaces (`refs/_blog/*`, `refs/kv/*`, etc.).
- Provide a tiny gateway that mirrors accepted refs to GitHub while rejecting bad pushes early.
- Keep custom ledgers (commit-message articles, KV, shiplog) safe from force pushes and unsigned writes.
```