Git Workflow & Merge Requests¶

CWIQ uses trunk-based development with short-lived feature branches.

Branching Model¶

main is the stable trunk — always deployable
All work happens on feature branches that merge back to main via Merge Request (MR)
Direct commits to main are prohibited
Feature branches should be short-lived (hours to days, not weeks)

Branch Naming Convention¶

Type	Format	Example
Feature	`feature/{scope}-{description}`	`feature/server-global-search`
Bug fix	`fix/{scope}-{description}`	`fix/ui-login-redirect-loop`
Refactor	`refactor/{scope}-{description}`	`refactor/server-auth-middleware`
Infrastructure	`infra/{scope}-{description}`	`infra/ansible-temporal-ha`

Rules:

{scope} = affected component: server, ui, agent, mcp, cli, executor, ansible, terraform
{description} = kebab-case, max 40 characters
All lowercase, hyphens only

Typical Workflow¶

1. Create a feature branch¶

git checkout main
git pull origin main
git checkout -b feature/server-add-search-endpoint

2. Make your changes¶

# Edit files...
git add src/api/search.py src/models/search.py
git commit -m "feat(search): add global search API endpoint"

3. Push and create a Merge Request¶

git push -u origin feature/server-add-search-endpoint \
  -o merge_request.create \
  -o merge_request.target=main \
  -o merge_request.title="feat(search): add global search API endpoint" \
  -o merge_request.remove_source_branch

This pushes your branch AND creates an MR in one command.

4. CI/CD pipeline runs automatically¶

The pipeline validates your code:

validate → test → build → deploy-dev → verify

5. Get review and merge¶

Assign reviewers
Address feedback
Once approved, merge via the GitLab UI

6. CI/CD deploys to DEV¶

After merging to main, the pipeline automatically deploys to the DEV environment.

Commit Message Convention¶

We use Conventional Commits:

<type>(<scope>): <description>

Type	When to Use
`feat`	New feature
`fix`	Bug fix
`refactor`	Code restructuring (no behavior change)
`docs`	Documentation only
`test`	Adding or fixing tests
`chore`	Build, CI, dependency updates
`ci`	CI/CD pipeline changes

Examples:

feat(search): add global search API endpoint
fix(auth): resolve login redirect loop on expired sessions
docs(api): update search endpoint documentation
chore(deps): upgrade FastAPI to 0.115

Multi-Repository Structure¶

CWIQ spans multiple repositories. A single feature may touch multiple repos:

Component	Repository	Type
Backend API	`orchestrator/server`	FastAPI
Frontend UI	`orchestrator/ui`	React
Agent	`orchestrator/agent`	Python CLI
MCP Server	`orchestrator/mcp`	FastAPI
CLI	`orchestrator/cli`	Typer
Executor	`orchestrator/executor`	Python CLI
Infrastructure	`sysadmins/ansible-playbooks`	Ansible
Cloud Resources	`sysadmins/terraform-plan`	Terraform

When a feature spans multiple repos, create separate branches in each and coordinate the MRs.