{"id":50886116,"url":"https://github.com/hops-ops/gitkb-stack","last_synced_at":"2026-06-15T17:02:41.083Z","repository":{"id":363529835,"uuid":"1263645461","full_name":"hops-ops/gitkb-stack","owner":"hops-ops","description":"Crossplane configuration for deploying GitKB stacks","archived":false,"fork":false,"pushed_at":"2026-06-09T08:42:15.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T10:22:30.319Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go Template","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hops-ops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T06:24:02.000Z","updated_at":"2026-06-09T08:40:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hops-ops/gitkb-stack","commit_stats":null,"previous_names":["hops-ops/gitkb-stack"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/hops-ops/gitkb-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Fgitkb-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Fgitkb-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Fgitkb-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Fgitkb-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hops-ops","download_url":"https://codeload.github.com/hops-ops/gitkb-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Fgitkb-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34372130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-15T17:02:40.094Z","updated_at":"2026-06-15T17:02:41.068Z","avatar_url":"https://github.com/hops-ops.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitkb-stack\n\nGitKB installs a GitKB sync server into Kubernetes and can expose many knowledge bases on one Gateway using repository-style paths such as `https://kb.ops.com.ai/hops-ops/hops`.\n\nThe XR installs the Hops `gitkb-server` chart from the GitHub Pages Helm repository at `https://hops-ops.github.io/gitkb-server-chart`.\n\n## Why GitKB?\n\n**Without GitKB:**\n\n- Agents keep local context that is hard to share across sessions.\n- Each knowledge base needs hand-managed storage, routing, and lifecycle.\n- Multiple repos behind one public endpoint require bespoke Gateway routes.\n\n**With GitKB:**\n\n- A single `GitKB` claim installs the server, storage, and Kubernetes wiring.\n- `spec.gitkb.org` and `spec.gitkb.repo` derive predictable public paths.\n- Gateway API, ExternalDNS, and optional cert-manager resources are rendered together.\n\n## The Journey\n\n## Getting Started\n\nStart with an internal-only install:\n\n```yaml\napiVersion: hops.ops.com.ai/v1alpha1\nkind: GitKB\nmetadata:\n  name: gitkb\nspec:\n  clusterName: pat-local\n  namespace: gitkb\n```\n\nThe chart creates a single GitKB StatefulSet, ClusterIP Service, and persistent volume by default. Set `persistence.enabled: false` for disposable local tests.\n\n## Growing\n\nEnable Gateway API exposure when the cluster already has a platform Gateway and ExternalDNS watching HTTPRoutes:\n\n```yaml\nspec:\n  gitkb:\n    org: hops-ops\n    repo: hops\n  exposure:\n    enabled: true\n    domain: kb.ops.com.ai\n    gatewayRef:\n      name: platform\n      namespace: istio-ingress\n      sectionName: https\n```\n\nThis renders an unauthenticated `HTTPRoute` for `spec.exposure.domain` and annotates it for ExternalDNS.\n\nBy default, the public route path is derived from `spec.gitkb.org` and `spec.gitkb.repo`:\n\n```text\nhttps://kb.ops.com.ai/hops-ops/hops\n```\n\nThe HTTPRoute matches that prefix and uses Gateway API `URLRewrite` to strip it before forwarding to `git-kb serve`. That lets multiple GitKB repos share one domain:\n\n```yaml\nspec:\n  gitkb:\n    org: hops-ops\n    repo: hops\n```\n\nOverride `exposure.pathPrefix` only when the public path should differ from `/\u003corg\u003e/\u003crepo\u003e`. For a dedicated domain, set `pathPrefix: /`.\n\n## Enterprise Scale\n\nIf the Gateway does not already serve a wildcard certificate for the domain, enable the cert-manager Certificate. The Gateway listener still needs to reference the resulting Secret; this stack does not mutate the Gateway object.\n\n```yaml\nspec:\n  exposure:\n    certificate:\n      enabled: true\n      secretName: gitkb-tls\n      secretNamespace: istio-ingress\n      issuerRef:\n        name: letsencrypt-production\n        kind: ClusterIssuer\n```\n\nAuthentication is intentionally not part of this pass. Public installs should add Gateway/OIDC policy before exposing writable GitKB sync traffic beyond trusted networks.\n\n## Import Existing\n\nUse the chart seed settings to restore an existing KB from a Secret-backed backup or bundle:\n\n```yaml\nspec:\n  seed:\n    mode: backup\n    secretRef:\n      name: gitkb-backup\n      key: backup.json\n```\n\nTo keep an existing PVC, set `persistence.existingClaim` and leave `persistence.enabled: true`.\n\n## Using GitKB\n\nConfigure the GitKB CLI remote to the status URL or to the same domain and repo path:\n\n```toml\n[sync.remotes.origin]\nurl = \"https://kb.ops.com.ai/hops-ops/hops\"\n```\n\nThe server route strips `/hops-ops/hops` before forwarding traffic to `git-kb serve`, so the CLI talks to the normal GitKB endpoints under that public path.\n\n## Status\n\nThe XR publishes the operational fields needed by downstream automation:\n\n- `status.ready` - true when namespace, Helm release, route, certificate, and usage protections are ready.\n- `status.release` - Helm release name, namespace, and readiness.\n- `status.service` - backend Service name, namespace, and port.\n- `status.exposure.domain` - public domain from `spec.exposure.domain`.\n- `status.exposure.pathPrefix` - effective path prefix, defaulting to `/\u003corg\u003e/\u003crepo\u003e`.\n- `status.exposure.url` - full public URL for the GitKB remote.\n- `status.exposure.routeReady` - composed HTTPRoute readiness.\n- `status.exposure.certificateReady` - composed Certificate readiness when enabled.\n\n## Composed Resources\n\n- `helm.m.crossplane.io/Release` - installs the `gitkb-server` chart.\n- `kubernetes.m.crossplane.io/Object` Namespace - creates the target namespace.\n- `kubernetes.m.crossplane.io/Object` HTTPRoute - optional Gateway API route when `exposure.enabled` is true.\n- `kubernetes.m.crossplane.io/Object` Certificate - optional cert-manager Certificate when `exposure.certificate.enabled` is true.\n- `protection.crossplane.io/Usage` - protects dependency deletion order once resources are ready.\n\n## Development\n\n```bash\nmake test\nmake render:all\nmake validate:all\nmake build\n```\n\nFor local control-plane testing:\n\n```bash\nhops config install --path xrs/stacks/k8s/gitkb --context colima\nkubectl --context colima apply -f local/gitkb.yaml\n```\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhops-ops%2Fgitkb-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhops-ops%2Fgitkb-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhops-ops%2Fgitkb-stack/lists"}