Skip to content

Team Collaboration

Jump to bottom
Griffen Fargo edited this page Oct 6, 2025 · 1 revision

This guide covers best practices for using coco in team environments, from small development teams to large enterprise organizations.

Quick Start for Teams

1. Create Shared Configuration

Create a .coco.config.json in your project root:

{
  "$schema": "https://git-co.co/schema.json",
  "mode": "interactive",
  "conventionalCommits": true,
  "includeBranchName": true,
  "defaultBranch": "main",
  "ignoredFiles": [
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "dist/*",
    "build/*"
  ],
  "ignoredExtensions": [
    ".map",
    ".min.js",
    ".min.css"
  ],
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "tokenLimit": 2048,
    "temperature": 0.3,
    "authentication": {
      "type": "APIKey"
    }
  }
}

2. Commit and Share

# Add config to version control
git add .coco.config.json
git commit -m "feat: add coco team configuration"

# Team members can now use consistent settings
# API keys are set individually via environment variables

3. Team Onboarding

# Each team member sets their API key
export OPENAI_API_KEY=sk-their-individual-key

# Or uses the setup wizard
coco init --scope project

Configuration Strategies

Strategy 1: Shared Config + Individual API Keys

Best for: Most teams, maintains consistency while allowing individual billing

{
  "conventionalCommits": true,
  "mode": "interactive",
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "authentication": {
      "type": "APIKey"
    }
  }
}

Team members set individual API keys:

export OPENAI_API_KEY=sk-individual-key

Strategy 2: Shared Ollama Server

Best for: Privacy-conscious teams, cost control, offline capability

{
  "conventionalCommits": true,
  "service": {
    "provider": "ollama",
    "model": "qwen2.5-coder:7b",
    "endpoint": "http://team-ollama-server:11434",
    "authentication": {
      "type": "None"
    }
  }
}

Server setup:

# On dedicated server
OLLAMA_HOST=0.0.0.0:11434 ollama serve
ollama pull qwen2.5-coder:7b

Strategy 3: Organization API Key

Best for: Enterprise teams with centralized billing

{
  "conventionalCommits": true,
  "service": {
    "provider": "openai",
    "model": "gpt-4o",
    "authentication": {
      "type": "APIKey",
      "credentials": {
        "apiKey": "${TEAM_OPENAI_API_KEY}"
      }
    }
  }
}

Set organization-wide key:

# In CI/CD or shared environment
export TEAM_OPENAI_API_KEY=sk-org-key

Team Standards & Conventions

Conventional Commits Standards

Establish team-wide conventional commit standards:

{
  "conventionalCommits": true,
  "service": {
    "model": "gpt-4o",
    "temperature": 0.2
  }
}

Commitlint Integration:

# Install commitlint for the team
npm install --save-dev @commitlint/config-conventional @commitlint/cli

# Create commitlint config
echo 'module.exports = {extends: ["@commitlint/config-conventional"]}' > commitlint.config.js

# Add to package.json
{
  "scripts": {
    "commit": "coco -i",
    "commit-check": "commitlint --edit $1"
  }
}

Branch Naming Conventions

Configure branch name inclusion for ticket tracking:

{
  "includeBranchName": true
}

Team branch naming standards:

# Feature branches
feature/PROJ-123-user-authentication
feature/add-payment-processing

# Bug fix branches  
fix/PROJ-456-login-timeout
hotfix/critical-security-patch

# Coco will automatically extract ticket IDs
coco --append-ticket  # Adds "Part of **PROJ-123**"

File Ignoring Standards

Establish consistent file ignoring across the team:

{
  "ignoredFiles": [
    "package-lock.json",
    "yarn.lock", 
    "pnpm-lock.yaml",
    "dist/*",
    "build/*",
    "coverage/*",
    ".env.local",
    "*.log"
  ],
  "ignoredExtensions": [
    ".map",
    ".min.js",
    ".min.css",
    ".bundle.js",
    ".chunk.js"
  ]
}

Git Hooks Integration

Pre-commit Hook

Automatically generate commit messages:

#!/bin/sh
# .git/hooks/pre-commit

# Check if coco is available
if command -v coco >/dev/null 2>&1; then
    echo "Generating commit message suggestion..."
    coco commit
    echo ""
    echo "Use 'coco -i' for interactive commit or 'git commit -m \"message\"' to override"
fi

Commit-msg Hook

Validate commit messages:

#!/bin/sh
# .git/hooks/commit-msg

# Validate with commitlint if available
if command -v commitlint >/dev/null 2>&1; then
    commitlint --edit $1
fi

Husky Integration

For teams using Husky:

# Install Husky
npm install --save-dev husky

# Initialize Husky
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "coco commit --verbose"

# Add commit-msg validation
npx husky add .husky/commit-msg "commitlint --edit \$1"

Package.json configuration:

{
  "scripts": {
    "prepare": "husky install",
    "commit": "coco -i"
  },
  "husky": {
    "hooks": {
      "pre-commit": "coco commit --verbose",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

CI/CD Integration

GitHub Actions

Commit Message Validation:

name: Validate Commits
on: [push, pull_request]

jobs:
  validate-commits:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: |
          npm install -g git-coco @commitlint/cli @commitlint/config-conventional
          
      - name: Validate commit messages
        run: |
          commitlint --from HEAD~1 --to HEAD --verbose

Automated Commit Generation:

name: Generate Commit Messages
on: 
  workflow_dispatch:
    inputs:
      branch:
        description: 'Branch to analyze'
        required: true
        default: 'main'

jobs:
  generate-commits:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Ollama (for privacy)
        run: |
          curl -fsSL https://ollama.ai/install.sh | sh
          ollama serve &
          sleep 10
          ollama pull qwen2.5-coder:3b
          
      - name: Install Coco
        run: npm install -g git-coco
        
      - name: Generate commit analysis
        run: |
          coco recap --last-week > commit-analysis.md
          
      - name: Upload analysis
        uses: actions/upload-artifact@v3
        with:
          name: commit-analysis
          path: commit-analysis.md

GitLab CI

# .gitlab-ci.yml
stages:
  - validate
  - analyze

validate-commits:
  stage: validate
  image: node:18
  script:
    - npm install -g @commitlint/cli @commitlint/config-conventional
    - commitlint --from $CI_MERGE_REQUEST_TARGET_BRANCH_SHA --to HEAD
  only:
    - merge_requests

analyze-commits:
  stage: analyze
  image: node:18
  script:
    - npm install -g git-coco
    - coco recap --last-week > commit-analysis.txt
  artifacts:
    reports:
      junit: commit-analysis.txt
  only:
    - schedules

Jenkins Pipeline

pipeline {
    agent any
    
    stages {
        stage('Setup') {
            steps {
                sh 'npm install -g git-coco @commitlint/cli'
            }
        }
        
        stage('Validate Commits') {
            steps {
                sh 'commitlint --from HEAD~5 --to HEAD'
            }
        }
        
        stage('Generate Analysis') {
            steps {
                sh 'coco recap --last-week > commit-analysis.txt'
                archiveArtifacts artifacts: 'commit-analysis.txt'
            }
        }
    }
}

Security Best Practices

API Key Management

Individual API Keys (Recommended):

# Each developer uses their own key
export OPENAI_API_KEY=sk-individual-key

# Add to personal shell profile
echo 'export OPENAI_API_KEY=sk-your-key' >> ~/.bashrc

Organization API Keys:

# Use secret management systems
# AWS Secrets Manager, Azure Key Vault, etc.

# In CI/CD, use encrypted environment variables
# GitHub: Repository Settings > Secrets
# GitLab: Settings > CI/CD > Variables

Never commit API keys:

# Add to .gitignore
echo '.env' >> .gitignore
echo '.coco.config.local.json' >> .gitignore

# Use environment-specific configs
.coco.config.json          # Shared team config (no API keys)
.coco.config.local.json    # Individual config (gitignored)

Network Security

Corporate Firewalls:

# Whitelist AI API endpoints
# OpenAI: api.openai.com (443)
# Anthropic: api.anthropic.com (443)

# For Ollama, use internal servers
{
  "service": {
    "endpoint": "http://internal-ollama.company.com:11434"
  }
}

Proxy Configuration:

# Set proxy for API calls
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# Or in coco config
{
  "service": {
    "requestOptions": {
      "proxy": "http://proxy.company.com:8080"
    }
  }
}

Team Onboarding

New Developer Setup

1. Repository Setup:

# Clone repository
git clone https://github.com/company/project.git
cd project

# Install dependencies (includes coco config)
npm install

2. Coco Setup:

# Run setup wizard (uses existing project config)
coco init --scope project

# Test configuration
coco --verbose commit

3. Verification:

# Make a test change
echo "// Test change" >> README.md
git add README.md

# Generate test commit
coco -i

# Should generate conventional commit format

Training Materials

Quick Reference Card:

# Essential commands for new team members
coco -i                    # Interactive commit (recommended)
coco --conventional        # Force conventional format
coco -a "context"          # Add extra context
coco --append-ticket       # Include ticket from branch name
coco recap --yesterday     # Summarize recent work

Team Documentation Template:

# Coco Usage Guidelines

## Our Standards
- Always use conventional commits (`coco --conventional`)
- Use interactive mode for review (`coco -i`)
- Include ticket IDs for features (`coco --append-ticket`)
- Add context for complex changes (`coco -a "explanation"`)

## Branch Naming
- Features: `feature/PROJ-123-description`
- Fixes: `fix/PROJ-456-description`
- Hotfixes: `hotfix/critical-issue-description`

## When to Use Manual Commits
- Merge commits
- Revert commits
- Emergency hotfixes (when coco unavailable)

Monitoring & Analytics

Usage Tracking

API Cost Monitoring:

# Track API usage per developer
# OpenAI: https://platform.openai.com/account/usage
# Anthropic: https://console.anthropic.com/account/usage

# Set up billing alerts
# Monitor token usage patterns

Commit Quality Metrics:

# Analyze commit message quality
git log --oneline --since="1 week ago" | wc -l

# Check conventional commit compliance
git log --oneline --since="1 week ago" --grep="^(feat|fix|docs):"

# Generate team reports
coco recap --last-month > team-monthly-report.md

Team Analytics

Commit Pattern Analysis:

# Most active contributors
git shortlog -sn --since="1 month ago"

# Commit type distribution
git log --oneline --since="1 month ago" | grep -E "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore):" | cut -d: -f1 | cut -d' ' -f2 | sort | uniq -c

# Generate changelog for releases
coco changelog --since-last-tag

Troubleshooting Team Issues

Common Team Problems

Inconsistent Commit Formats:

# Solution: Enforce with git hooks
npx husky add .husky/commit-msg "commitlint --edit \$1"

# Or use pre-commit validation
npx husky add .husky/pre-commit "coco --conventional --verbose"

API Cost Concerns:

# Solution: Use Ollama for cost control
{
  "service": {
    "provider": "ollama",
    "model": "qwen2.5-coder:7b",
    "endpoint": "http://team-server:11434"
  }
}

# Or set token limits
{
  "service": {
    "tokenLimit": 1024,
    "maxConcurrent": 1
  }
}

Configuration Conflicts:

# Solution: Clear priority hierarchy
# 1. Use project config for team standards
# 2. Use environment variables for individual settings
# 3. Document override procedures

# Example: Individual model preference
export COCO_SERVICE_MODEL=gpt-3.5-turbo  # Overrides project config

Advanced Team Configurations

Multi-Project Organizations

Shared Configuration Repository:

# Create shared config repository
git clone https://github.com/company/coco-configs.git

# Symlink configs to projects
ln -s ../coco-configs/frontend.json .coco.config.json
ln -s ../coco-configs/backend.json .coco.config.json

Project-Specific Customizations:

{
  "extends": "@company/coco-config-base",
  "ignoredFiles": [
    "project-specific-file.js"
  ],
  "service": {
    "model": "gpt-4o"
  }
}

Enterprise Integration

LDAP/SSO Integration:

# Use organization API keys with SSO
# Integrate with corporate identity providers
# Audit trail for API usage

Compliance & Auditing:

# Log all coco usage
export COCO_AUDIT_LOG=/var/log/coco-audit.log

# Track commit generation
git log --grep="Generated by coco" --since="1 month ago"

This guide provides a comprehensive framework for successful team adoption of coco, from initial setup to enterprise-scale deployment.

Clone this wiki locally