zulip-platform-plugins/docs/GITOPS.md

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:

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:

./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

./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