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:

json

1{
2  "$schema": "https://git-co.co/schema.json",
3  "mode": "interactive",
4  "conventionalCommits": true,
5  "includeBranchName": true,
6  "defaultBranch": "main",
7  "ignoredFiles": [
8    "package-lock.json",
9    "yarn.lock",
10    "pnpm-lock.yaml",
11    "dist/*",
12    "build/*"
13  ],
14  "ignoredExtensions": [
15    ".map",
16    ".min.js",
17    ".min.css"
18  ],
19  "service": {
20    "provider": "openai",
21    "model": "gpt-4o",
22    "tokenLimit": 2048,
23    "temperature": 0.3,
24    "authentication": {
25      "type": "APIKey"
26    }
27  }
28}

2. Commit and Share

bash

1# Add config to version control
2git add .coco.config.json
3git commit -m "feat: add coco team configuration"
4
5# Team members can now use consistent settings
6# API keys are set individually via environment variables

3. Team Onboarding

bash

1# Each team member sets their API key
2export OPENAI_API_KEY=sk-their-individual-key
3
4# Or uses the setup wizard
5coco init --scope project

Configuration Strategies

Strategy 1: Shared Config + Individual API Keys

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

json

1{
2  "conventionalCommits": true,
3  "mode": "interactive",
4  "service": {
5    "provider": "openai",
6    "model": "gpt-4o",
7    "authentication": {
8      "type": "APIKey"
9    }
10  }
11}

Team members set individual API keys:

bash

export OPENAI_API_KEY=sk-individual-key

Strategy 2: Shared Ollama Server

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

json

1{
2  "conventionalCommits": true,
3  "service": {
4    "provider": "ollama",
5    "model": "qwen2.5-coder:7b",
6    "endpoint": "http://team-ollama-server:11434",
7    "authentication": {
8      "type": "None"
9    }
10  }
11}

Server setup:

bash

# 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

json

1{
2  "conventionalCommits": true,
3  "service": {
4    "provider": "openai",
5    "model": "gpt-4o",
6    "authentication": {
7      "type": "APIKey",
8      "credentials": {
9        "apiKey": "${TEAM_OPENAI_API_KEY}"
10      }
11    }
12  }
13}

Set organization-wide key:

bash

# 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:

json

1{
2  "conventionalCommits": true,
3  "service": {
4    "model": "gpt-4o",
5    "temperature": 0.2
6  }
7}

Commitlint Integration:

bash

1# Install commitlint for the team
2npm install --save-dev @commitlint/config-conventional @commitlint/cli
3
4# Create commitlint config
5echo 'module.exports = {extends: ["@commitlint/config-conventional"]}' > commitlint.config.js
6
7# Add to package.json
8{
9  "scripts": {
10    "commit": "coco -i",
11    "commit-check": "commitlint --edit $1"
12  }
13}

Branch Naming Conventions

Configure branch name inclusion for ticket tracking:

json

{
  "includeBranchName": true
}

Team branch naming standards:

bash

1# Feature branches
2feature/PROJ-123-user-authentication
3feature/add-payment-processing
4
5# Bug fix branches  
6fix/PROJ-456-login-timeout
7hotfix/critical-security-patch
8
9# Coco will automatically extract ticket IDs
10coco commit --append-ticket  # Adds "Part of **PROJ-123**"

File Ignoring Standards

Establish consistent file ignoring across the team:

json

1{
2  "ignoredFiles": [
3    "package-lock.json",
4    "yarn.lock", 
5    "pnpm-lock.yaml",
6    "dist/*",
7    "build/*",
8    "coverage/*",
9    ".env.local",
10    "*.log"
11  ],
12  "ignoredExtensions": [
13    ".map",
14    ".min.js",
15    ".min.css",
16    ".bundle.js",
17    ".chunk.js"
18  ]
19}

Git Hooks Integration

Pre-commit Hook

Automatically generate commit messages:

bash

1#!/bin/sh
2# .git/hooks/pre-commit
3
4# Check if coco is available
5if command -v coco >/dev/null 2>&1; then
6    echo "Generating commit message suggestion..."
7    coco commit
8    echo ""
9    echo "Use 'coco -i' for interactive commit or 'git commit -m \"message\"' to override"
10fi

Commit-msg Hook

Validate commit messages:

bash

1#!/bin/sh
2# .git/hooks/commit-msg
3
4# Validate with commitlint if available
5if command -v commitlint >/dev/null 2>&1; then
6    commitlint --edit $1
7fi

Husky Integration

For teams using Husky:

bash

1# Install Husky
2npm install --save-dev husky
3
4# Initialize Husky
5npx husky install
6
7# Add pre-commit hook
8npx husky add .husky/pre-commit "coco commit --verbose"
9
10# Add commit-msg validation
11npx husky add .husky/commit-msg "commitlint --edit \$1"

Package.json configuration:

json

1{
2  "scripts": {
3    "prepare": "husky install",
4    "commit": "coco -i"
5  },
6  "husky": {
7    "hooks": {
8      "pre-commit": "coco commit --verbose",
9      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
10    }
11  }
12}

CI/CD Integration

GitHub Actions

Commit Message Validation:

yaml

1name: Validate Commits
2on: [push, pull_request]
3
4jobs:
5  validate-commits:
6    runs-on: ubuntu-latest
7    steps:
8      - uses: actions/checkout@v3
9        with:
10          fetch-depth: 0
11          
12      - name: Setup Node.js
13        uses: actions/setup-node@v3
14        with:
15          node-version: '18'
16          
17      - name: Install dependencies
18        run: |
19          npm install -g git-coco @commitlint/cli @commitlint/config-conventional
20          
21      - name: Validate commit messages
22        run: |
23          commitlint --from HEAD~1 --to HEAD --verbose

Automated Commit Generation:

yaml

1name: Generate Commit Messages
2on: 
3  workflow_dispatch:
4    inputs:
5      branch:
6        description: 'Branch to analyze'
7        required: true
8        default: 'main'
9
10jobs:
11  generate-commits:
12    runs-on: ubuntu-latest
13    steps:
14      - uses: actions/checkout@v3
15      
16      - name: Setup Ollama (for privacy)
17        run: |
18          curl -fsSL https://ollama.ai/install.sh | sh
19          ollama serve &
20          sleep 10
21          ollama pull qwen2.5-coder:3b
22          
23      - name: Install Coco
24        run: npm install -g git-coco
25        
26      - name: Generate commit analysis
27        run: |
28          coco recap --last-week > commit-analysis.md
29          
30      - name: Upload analysis
31        uses: actions/upload-artifact@v3
32        with:
33          name: commit-analysis
34          path: commit-analysis.md

GitLab CI

yaml

1# .gitlab-ci.yml
2stages:
3  - validate
4  - analyze
5
6validate-commits:
7  stage: validate
8  image: node:18
9  script:
10    - npm install -g @commitlint/cli @commitlint/config-conventional
11    - commitlint --from $CI_MERGE_REQUEST_TARGET_BRANCH_SHA --to HEAD
12  only:
13    - merge_requests
14
15analyze-commits:
16  stage: analyze
17  image: node:18
18  script:
19    - npm install -g git-coco
20    - coco recap --last-week > commit-analysis.txt
21  artifacts:
22    reports:
23      junit: commit-analysis.txt
24  only:
25    - schedules

Jenkins Pipeline

groovy

1pipeline {
2    agent any
3    
4    stages {
5        stage('Setup') {
6            steps {
7                sh 'npm install -g git-coco @commitlint/cli'
8            }
9        }
10        
11        stage('Validate Commits') {
12            steps {
13                sh 'commitlint --from HEAD~5 --to HEAD'
14            }
15        }
16        
17        stage('Generate Analysis') {
18            steps {
19                sh 'coco recap --last-week > commit-analysis.txt'
20                archiveArtifacts artifacts: 'commit-analysis.txt'
21            }
22        }
23    }
24}

Security Best Practices

API Key Management

Individual API Keys (Recommended):

bash

1# Each developer uses their own key
2export OPENAI_API_KEY=sk-individual-key
3
4# Add to personal shell profile
5echo 'export OPENAI_API_KEY=sk-your-key' >> ~/.bashrc

Organization API Keys:

bash

1# Use secret management systems
2# AWS Secrets Manager, Azure Key Vault, etc.
3
4# In CI/CD, use encrypted environment variables
5# GitHub: Repository Settings > Secrets
6# GitLab: Settings > CI/CD > Variables

Never commit API keys:

bash

1# Add to .gitignore
2echo '.env' >> .gitignore
3echo '.coco.config.local.json' >> .gitignore
4
5# Use environment-specific configs
6.coco.config.json          # Shared team config (no API keys)
7.coco.config.local.json    # Individual config (gitignored)

Network Security

Corporate Firewalls:

bash

1# Whitelist AI API endpoints
2# OpenAI: api.openai.com (443)
3# Anthropic: api.anthropic.com (443)
4
5# For Ollama, use internal servers
6{
7  "service": {
8    "endpoint": "http://internal-ollama.company.com:11434"
9  }
10}

Proxy Configuration:

bash

1# Set proxy for API calls
2export HTTPS_PROXY=http://proxy.company.com:8080
3export HTTP_PROXY=http://proxy.company.com:8080
4
5# Or in coco config
6{
7  "service": {
8    "requestOptions": {
9      "proxy": "http://proxy.company.com:8080"
10    }
11  }
12}

Team Onboarding

New Developer Setup

1. Repository Setup:

bash

1# Clone repository
2git clone https://github.com/company/project.git
3cd project
4
5# Install dependencies (includes coco config)
6npm install

2. Coco Setup:

bash

1# Run setup wizard (uses existing project config)
2coco init --scope project
3
4# Test configuration
5coco commit --verbose

3. Verification:

bash

1# Make a test change
2echo "// Test change" >> README.md
3git add README.md
4
5# Generate test commit
6coco commit -i
7
8# Should generate conventional commit format

Training Materials

Quick Reference Card:

bash

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

Team Documentation Template:

markdown

1# Coco Usage Guidelines
2
3## Our Standards
4- Always use conventional commits (`coco --conventional`)
5- Use interactive mode for review (`coco -i`)
6- Include ticket IDs for features (`coco --append-ticket`)
7- Add context for complex changes (`coco -a "explanation"`)
8
9## Branch Naming
10- Features: `feature/PROJ-123-description`
11- Fixes: `fix/PROJ-456-description`
12- Hotfixes: `hotfix/critical-issue-description`
13
14## When to Use Manual Commits
15- Merge commits
16- Revert commits
17- Emergency hotfixes (when coco unavailable)

Monitoring & Analytics

Usage Tracking

API Cost Monitoring:

bash

1# Track API usage per developer
2# OpenAI: https://platform.openai.com/account/usage
3# Anthropic: https://console.anthropic.com/account/usage
4
5# Set up billing alerts
6# Monitor token usage patterns

Commit Quality Metrics:

bash

1# Analyze commit message quality
2git log --oneline --since="1 week ago" | wc -l
3
4# Check conventional commit compliance
5git log --oneline --since="1 week ago" --grep="^(feat|fix|docs):"
6
7# Generate team reports
8coco recap --last-month > team-monthly-report.md

Team Analytics

Commit Pattern Analysis:

bash

1# Most active contributors
2git shortlog -sn --since="1 month ago"
3
4# Commit type distribution
5git 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
6
7# Generate changelog for releases
8coco changelog --since-last-tag

Troubleshooting Team Issues

Common Team Problems

Inconsistent Commit Formats:

bash

1# Solution: Enforce with git hooks
2npx husky add .husky/commit-msg "commitlint --edit \$1"
3
4# Or use pre-commit validation
5npx husky add .husky/pre-commit "coco --conventional --verbose"

API Cost Concerns:

bash

1# Solution: Use Ollama for cost control
2{
3  "service": {
4    "provider": "ollama",
5    "model": "qwen2.5-coder:7b",
6    "endpoint": "http://team-server:11434"
7  }
8}
9
10# Or set token limits
11{
12  "service": {
13    "tokenLimit": 1024,
14    "maxConcurrent": 1
15  }
16}

Configuration Conflicts:

bash

1# Solution: Clear priority hierarchy
2# 1. Use project config for team standards
3# 2. Use environment variables for individual settings
4# 3. Document override procedures
5
6# Example: Individual model preference
7export COCO_SERVICE_MODEL=gpt-3.5-turbo  # Overrides project config

Advanced Team Configurations

Multi-Project Organizations

Shared Configuration Repository:

bash

1# Create shared config repository
2git clone https://github.com/company/coco-configs.git
3
4# Symlink configs to projects
5ln -s ../coco-configs/frontend.json .coco.config.json
6ln -s ../coco-configs/backend.json .coco.config.json

Project-Specific Customizations:

json

1{
2  "extends": "@company/coco-config-base",
3  "ignoredFiles": [
4    "project-specific-file.js"
5  ],
6  "service": {
7    "model": "gpt-4o"
8  }
9}

Enterprise Integration

LDAP/SSO Integration:

bash

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

Compliance & Auditing:

bash

1# Log all coco usage
2export COCO_AUDIT_LOG=/var/log/coco-audit.log
3
4# Track commit generation
5git 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.