~/.config/goose/profiles.yaml (Global)
↓
project/.goose/profiles.yaml (Project)
↓
CLI flags/environment variables (Runtime)

Hacktoberfest: Maintainer Spotlight

Introduction

Working with Goose across multiple projects comes with challenges. One major issue is the time and effort it takes for teams to set up configurations: “Wait, what provider did we use for this React app? Which LLM model for the Django server? Did you turn off auto-execute for this SECRET project?”

Without a systematic structure, teams constantly ask these questions and fix inconsistencies. Luckily, Goose allows developers to manage project configurations easily through global and project YAML files.

---

Understanding Goose Configuration Layers

Goose configurations work in a hierarchy:

~/.config/goose/profiles.yaml (Global)
↓
project/.goose/profiles.yaml (Project)
↓
CLI flags/environment variables (Runtime)

Each layer overrides the previous one, giving you flexibility in configuration structure.

---

Configuration Management Strategies

1. The Template Approach

Create a central repository of configuration templates:

# templates/base-profile.yaml
provider: openai
processor: gpt-4
accelerator: gpt-4-turbo

# my-project/.goose/profiles.yaml
extends: ../../templates/base-profile.yaml
toolkits:
- name: developer
- name: github
requires:
GITHUB_TOKEN: ${GITHUB_TOKEN}

2. Centralized Config Repository

goose-configs/
├── profiles/
│   ├── development.yaml
│   ├── production.yaml
│   └── testing.yaml
└── scripts/
├── sync-config.sh
└── validate-config.sh

Sync script:

#!/bin/bash
CONFIG_REPO="$HOME/goose-configs"
cp "$CONFIG_REPO/profiles/$1.yaml" ".goose/profiles.yaml"
echo "Synced $1 profile"

3. Version Control Integration

.goose/profiles.yaml
!.goose/profiles.template.yaml
.goose/.env

---

Automation Strategies

Configuration Validation

# validate_config.py
import yaml, sys

REQUIRED_FIELDS = ['provider', 'processor']
with open('.goose/profiles.yaml', 'r') as f:
config = yaml.safe_load(f)

missing = [f for f in REQUIRED_FIELDS if f not in config]
if missing:
print(f"Missing: {missing}")
sys.exit(1)
print("✓ Valid")

Environment Switcher

#!/bin/bash
ENV=$1
if [ -f ".goose/profiles.$ENV.yaml" ]; then
cp ".goose/profiles.$ENV.yaml" ".goose/profiles.yaml"
echo "Switched to $ENV"
fi

---

Troubleshooting

Issue 1: Configuration Not Loading

goose config show  # Check which config is loaded

Checklist:

• ✅ File named profiles.yaml
• ✅ Located at .goose/profiles.yaml
• ✅ Valid YAML syntax

Issue 2: Environment Variables Not Resolving

#!/bin/bash
for var in "GITHUB_TOKEN" "OPENAI_API_KEY"; do
[ -z "${!var}" ] && echo "❌ $var not set" || echo "✓ $var set"
done

Issue 3: Conflicting Configurations

Resolution order:

1. CLI flags
2. Project config (.goose/profiles.yaml)
3. Global config (~/.config/goose/profiles.yaml)

---

Scaling Strategies

Small Teams (2-5 developers)

• 📁 Shared folder for templates
• 🔄 Simple shell scripts
• 📝 README documentation

Medium Teams (5-20 developers)

• 📦 Dedicated config repository
• ✅ CI/CD validation
• 🌍 Environment-specific configs

Large Organizations (20+ developers)

• 🏗️ Configuration-as-code
• 🛠️ Centralized management tools
• 🤖 Automated deployment

---

Best Practices Checklist

✅ Version Control

• [ ] Templates in version control
• [ ] Secrets excluded
• [ ] Proper .gitignore

✅ Documentation

• [ ] Configuration docs per project
• [ ] Environment variables documented
• [ ] Clear setup instructions

✅ Automation

• [ ] CI validation
• [ ] Sync scripts available
• [ ] Automated environment switching

✅ Security

• [ ] Environment variables for API keys
• [ ] No committed secrets
• [ ] Documented access controls

---

Real-World Example

company-goose-configs/
├── profiles/
│   ├── backend-dev.yaml
│   ├── frontend-dev.yaml
│   └── data-science.yaml
└── scripts/
└── install.sh

Install script:

#!/bin/bash
PROJECT_TYPE=$1
mkdir -p .goose
cp "profiles/$PROJECT_TYPE.yaml" ".goose/profiles.yaml"
echo "✓ Configured for $PROJECT_TYPE"