Abiba (pi)
ea262a38bb
CI / validate (push) Failing after 11s
- docs/GITOPS.md: complete workflow from prototype to production - .gitea/pull_request_template.md: pre-merge checklist for swarm PR review - scripts/deploy.sh: tag-based deployment to all 6 CTs with health checks - scripts/rollback.sh: rollback to previous tag - .gitea/workflows/ci.yml: CI pipeline (activates when Actions runners available) - .gitignore: prevent config.yaml and secrets from being committed - .gitattributes: consistent LF line endings across platforms
144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# GitOps Workflow — zulip-platform-plugins
|
|
|
|
## Overview
|
|
|
|
This document defines the development workflow from prototype to production maintenance for the multi-platform Zulip agent communication plugins. It replaces the current "everyone pushes to main" approach with a structured pipeline that supports swarm development across 6 CTs.
|
|
|
|
## Branch Strategy
|
|
|
|
```
|
|
main ← PROTECTED — production code. PR + review required.
|
|
│
|
|
├── feat/* ← Feature branches (e.g., feat/issue-5-hermes-core)
|
|
├── fix/* ← Bug fixes (e.g., fix/acl-spoofing)
|
|
├── docs/* ← Documentation only
|
|
└── release/* ← Release candidates for staging validation
|
|
```
|
|
|
|
### Branch Naming Convention
|
|
|
|
| Prefix | Purpose | Example |
|
|
|--------|---------|---------|
|
|
| `feat/` | New feature or enhancement | `feat/issue-5-hermes-core-adapter` |
|
|
| `fix/` | Bug fix | `fix/private-topic-acl-spoof` |
|
|
| `docs/` | Documentation changes | `docs/add-deployment-guide` |
|
|
| `release/` | Pre-production release candidate | `release/v1.0.0-rc1` |
|
|
| `hotfix/` | Emergency production fix | `hotfix/zulip-sdk-reconnect` |
|
|
|
|
### Branch Protection (main)
|
|
|
|
Apply via Gitea UI: `Settings > Branches > Add Rule`
|
|
|
|
```
|
|
Branch: main
|
|
- [x] Enable Push Restriction (restrict to repository admins only)
|
|
- [x] Require Pull Request to merge (approvals: 1)
|
|
- [x] Dismiss stale reviews when new commits are pushed
|
|
- [x] Block merge if status checks fail (when CI is added)
|
|
```
|
|
|
|
## Development Flow
|
|
|
|
### Phase 1: Prototype (per-agent CT)
|
|
|
|
```
|
|
1. Agent clones repo on their CT
|
|
2. Creates feat/ branch from main
|
|
3. Implements plugin code
|
|
4. Tests locally on their CT (health endpoint, Zulip connect)
|
|
5. Opens PR to main
|
|
6. Review by Kwame or designated reviewer
|
|
7. Merge → main
|
|
```
|
|
|
|
### Phase 2: Integration Testing
|
|
|
|
```
|
|
1. Tag main: git tag -a v0.1.0 -m "Integration test release"
|
|
2. Push tag: git push origin v0.1.0
|
|
3. Run: ./scripts/deploy.sh v0.1.0
|
|
4. deploy.sh SSHs to each CT and checks out the tag
|
|
5. Run E2E test suite (#17) against deployed tag
|
|
6. If all pass → promote to v1.0.0
|
|
```
|
|
|
|
### Phase 3: Production
|
|
|
|
```
|
|
1. Tag main: git tag -a v1.0.0 -m "Production release"
|
|
2. Push tag
|
|
3. Run: ./scripts/deploy.sh v1.0.0
|
|
4. Verify health endpoints on all 6 CTs
|
|
5. Monitor Zulip #agent-hub for agent responses
|
|
```
|
|
|
|
### Phase 4: Maintenance
|
|
|
|
```
|
|
1. Bug reported → fix/ branch from main
|
|
2. Fix + test → PR → review → merge
|
|
3. Tag patch release: v1.0.1
|
|
4. deploy.sh v1.0.1 (can be per-CT for targeted fixes)
|
|
5. Update ADRs if the fix changes a decision
|
|
```
|
|
|
|
## Versioning
|
|
|
|
Semantic versioning: `MAJOR.MINOR.PATCH`
|
|
|
|
| Bump | When |
|
|
|------|------|
|
|
| MAJOR | Breaking change to plugin contract, config schema, or Zulip API |
|
|
| MINOR | New feature, new ADR, new platform support |
|
|
| PATCH | Bug fix, doc update, config tweak |
|
|
|
|
Tag format: `v{MAJOR}.{MINOR}.{PATCH}` — e.g., `v1.0.0`
|
|
|
|
## CI/CD (Future — Gitea Actions)
|
|
|
|
When Gitea Actions runners are configured, add `.gitea/workflows/ci.yml`:
|
|
|
|
```yaml
|
|
on: [pull_request, push]
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- name: Validate config schema
|
|
run: python3 -c "import yaml; yaml.safe_load(open('config.yaml.example'))"
|
|
- name: Lint Python
|
|
run: ruff check hermes-zulip-plugin/ agent-zero-plugin/
|
|
- name: TypeScript check
|
|
run: cd pi-zulip-extension && npm ci && npx tsc --noEmit
|
|
```
|
|
|
|
## deploy.sh Contract
|
|
|
|
`deploy.sh` accepts a tag or branch as its argument:
|
|
|
|
```bash
|
|
./scripts/deploy.sh v1.0.0 # Deploy specific release
|
|
./scripts/deploy.sh main # Deploy latest (staging only)
|
|
./scripts/deploy.sh --ct=tanko v1.0.0 # Single-CT deploy
|
|
```
|
|
|
|
### Deploy behavior:
|
|
1. SSH into each CT
|
|
2. `cd /path/to/plugin && git fetch --tags && git checkout $TAG`
|
|
3. Install/update dependencies (pip install -r requirements.txt / npm ci)
|
|
4. Restart plugin service (systemctl restart zulip-plugin)
|
|
5. Verify health endpoint responds 200
|
|
6. Log result to `deploy.log`
|
|
|
|
## Rollback
|
|
|
|
```bash
|
|
./scripts/rollback.sh v0.9.0 # Rollback all CTs to previous tag
|
|
./scripts/rollback.sh --ct=abiba v0.9.0 # Single-CT rollback
|
|
```
|
|
|
|
## Pre-Merge Checklist (PR Template)
|
|
|
|
See `.gitea/pull_request_template.md`
|