# FAQ & Troubleshooting Guide: Security-Focused CWD Operations
## Frequently Asked Questions
### Q1: Why can't I specify a repository path anymore?
**A:** This is a deliberate security decision. By restricting all operations to the current working directory, we eliminate entire categories of security vulnerabilities including path traversal attacks and unauthorized directory access. You must now `cd` to the directory you want to work with before running commands.
### Q2: How do I work with multiple repositories?
**A:** You need to change directories between operations:
```bash
# Old way (v1.x)
commit_helper get_git_status --repo-path /repo1
commit_helper get_git_status --repo-path /repo2
# New way (v2.0)
cd /repo1 && commit_helper get_git_status
cd /repo2 && commit_helper get_git_status
```
For scripts, save and restore the original directory:
```bash
ORIGINAL_DIR=$(pwd)
cd /repo1 && commit_helper get_git_status
cd /repo2 && commit_helper get_git_status
cd "$ORIGINAL_DIR"
```
### Q3: What happened to the COMMITIZEN_REPO_PATH environment variable?
**A:** It has been completely removed. Environment variables are a potential security risk as they can be manipulated to access unintended directories. All operations now work exclusively on the current working directory.
### Q4: Will my existing scripts break?
**A:** Yes, this is a breaking change. Any code that passes `repo_path` parameters or relies on environment variables will need to be updated. See the migration guide for detailed instructions.
### Q5: Can I still use this in CI/CD pipelines?
**A:** Yes! CI/CD pipelines typically already change to the correct directory before running commands. You may need to update your pipeline scripts:
```yaml
# Old GitHub Actions example
- name: Generate commit message
run: commit_helper generate_commit_message --repo-path ${{ github.workspace }}
# New GitHub Actions example
- name: Generate commit message
working-directory: ${{ github.workspace }}
run: commit_helper generate_commit_message
```
### Q6: Is this less convenient than before?
**A:** For single-repository workflows, there's no change in convenience. For multi-repository workflows, yes, it requires explicit directory changes. However, this trade-off provides significant security benefits and makes the operation scope explicit and clear.
### Q7: Should I install commit-helper-mcp globally or as a dev dependency?
**A:** We recommend installing it as a dev dependency in each project. This approach:
- Ensures proper access to your git repository
- Maintains the security model (CWD-only operations)
- Allows different projects to use different versions
- Makes the dependency explicit and version-controlled
See [Dev Dependency Approach](./13-dev-dependency-approach.md) for detailed instructions.
### Q8: How do I configure the MCP server when using it as a dev dependency?
**A:** Use `uv run` (or your package manager's equivalent) without isolation flags:
```json
{
"mcpServers": {
"commit-helper-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "commit_helper_mcp.main"]
}
}
}
```
This ensures the MCP server runs in your project's context with access to the git repository.
## Common Issues & Solutions
### Issue 1: "TypeError: got an unexpected keyword argument 'repo_path'"
**Symptoms:**
```python
TypeError: get_git_status() got an unexpected keyword argument 'repo_path'
```
**Cause:** You're trying to use the old API with `repo_path` parameters.
**Solution:** Remove all `repo_path` parameters from your tool calls:
```python
# Old
result = get_git_status(repo_path="/some/path")
# New
os.chdir("/some/path")
result = get_git_status()
```
### Issue 2: "Current directory is not a git repository"
**Symptoms:**
```json
{
"success": false,
"error": "Current directory is not a git repository",
"error_type": "RepositoryError"
}
```
**Solutions:**
1. Ensure you're in the correct directory: `pwd`
2. Check if it's a git repository: `ls -la .git`
3. Initialize git if needed: `git init`
4. Change to the correct directory: `cd /path/to/repo`
### Issue 3: "No read access to current working directory"
**Symptoms:**
```json
{
"success": false,
"error": "No read access to current working directory",
"error_type": "RepositoryError"
}
```
**Solutions:**
1. Check permissions: `ls -la .`
2. Fix permissions: `chmod +r .`
3. Ensure you have proper user permissions
4. Check if the directory still exists
### Issue 4: Environment variable not working
**Symptoms:**
- Setting `COMMITIZEN_REPO_PATH` has no effect
- Operations still use current directory
**Explanation:** This is expected behavior. Environment variables are no longer supported for security reasons. You must change to the target directory.
### Issue 5: Multi-repository scripts failing
**Symptoms:**
- Scripts that process multiple repositories no longer work
- Only the first repository is processed
**Solution:** Update your scripts to change directories:
```python
# Old approach
for repo in repos:
process_repo(repo_path=repo)
# New approach
original_dir = os.getcwd()
try:
for repo in repos:
os.chdir(repo)
process_repo()
finally:
os.chdir(original_dir)
```
## Migration Troubleshooting
### Problem: Large codebase with many repo_path uses
**Solution:** Use a systematic approach:
1. Search for all `repo_path` occurrences
2. Create a wrapper function for migration period
3. Update code incrementally
4. Test thoroughly
Example wrapper:
```python
def migrate_tool_call(tool_func, repo_path=None, **kwargs):
"""Temporary wrapper for migration."""
if repo_path:
original = os.getcwd()
try:
os.chdir(repo_path)
return tool_func(**kwargs)
finally:
os.chdir(original)
else:
return tool_func(**kwargs)
```
### Problem: CI/CD pipeline failures
**Solution:** Update pipeline configurations:
```yaml
# Update working directory in steps
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Run commit helper
working-directory: ${{ github.workspace }}
run: |
commit_helper get_git_status
commit_helper generate_commit_message
```
### Problem: Docker container issues
**Solution:** Set WORKDIR in Dockerfile:
```dockerfile
FROM python:3.13
WORKDIR /app
COPY . .
# Commands will run in /app directory
RUN commit_helper validate_commit_readiness
```
## Security Benefits Explained
### Why CWD-Only?
1. **Prevents Path Traversal**: Cannot access `../../../etc/passwd`
2. **Explicit Scope**: Always clear which directory is being operated on
3. **No Hidden State**: No environment variables or context that could be manipulated
4. **Audit Trail**: Directory changes are explicit in logs
### What attacks does this prevent?
1. **Path Traversal Attacks**: Cannot access parent directories
2. **Environment Variable Injection**: No environment variables used
3. **Confused Deputy**: Tool cannot be tricked into accessing wrong directory
4. **Directory Hijacking**: Explicit directory changes are visible
## Performance Considerations
### Is it slower?
**No**, it's actually faster:
- No path resolution logic
- No environment variable checks
- No context provider overhead
- Direct operation on CWD
### Benchmarks
```python
# Old approach: ~5ms overhead
- Check explicit parameter
- Check environment variable
- Check context provider
- Validate path
- Execute
# New approach: ~1ms overhead
- Validate CWD
- Execute
```
## Best Practices
### 1. Always restore original directory
```python
original = os.getcwd()
try:
os.chdir(target_dir)
# Do work
finally:
os.chdir(original)
```
### 2. Use context managers
```python
from contextlib import contextmanager
@contextmanager
def in_directory(path):
original = os.getcwd()
try:
os.chdir(path)
yield
finally:
os.chdir(original)
# Usage
with in_directory("/path/to/repo"):
result = get_git_status()
```
### 3. Clear error handling
```python
try:
os.chdir(repo_path)
except FileNotFoundError:
print(f"Repository not found: {repo_path}")
except PermissionError:
print(f"No access to: {repo_path}")
```
### 4. Document directory requirements
```python
def my_script():
"""
Script to process repository.
Must be run from repository root directory.
"""
if not os.path.exists(".git"):
raise RuntimeError("Must be run from repository root")
```
## Getting Help
If you encounter issues not covered here:
1. **Check current directory**: `pwd`
2. **Verify it's a git repo**: `git status`
3. **Check permissions**: `ls -la`
4. **Review error messages**: They now clearly indicate CWD issues
5. **Read migration guide**: See `MIGRATION_v2.md`
## Summary
The security-focused CWD-only approach:
- **Eliminates** path-based security vulnerabilities
- **Simplifies** the codebase significantly
- **Requires** explicit directory navigation
- **Provides** clear, predictable behavior
- **Improves** overall system security
While it requires changes to existing workflows, the security and simplicity benefits make it worthwhile.
