Git Environment

A Git server environment using Gitea that provides isolated Git repository management optimized for task-based RL training. Perfect for training agents on Git operations with fast reset capabilities.

Overview

The Git Environment connects to a shared external Gitea service for optimal task-based isolation. Perfect for: RL training, task-based workflows, parallel execution

Architecture

┌────────────────────────────────────┐
│ Shared Gitea (start once)          │
│ Port 3000                          │
│ - Pre-migrated repositories        │
└──────────────┬─────────────────────┘
               │ HTTP API
      ┾────────┼────────┾
      │        │        │
  ┌───▼──┐ ┌──▼───┐ ┌──▼───┐
  │Env 1 │ │Env 2 │ │Env 3 │
  │Task A│ │Task B│ │Task A│
  │@abc  │ │@def  │ │@abc  │
  └──────┘ └──────┘ └──────┘
  Isolated workspaces

Quick Start

from envs.git_env import GitAction, GitEnv

# Create environment from Docker image
git_env = GitEnv.from_docker_image("git-env:latest")

# Reset environment
result = git_env.reset()
print(result.observation.message)

# List available repositories (pre-migrated to shared Gitea)
result = git_env.step(GitAction(action_type="list_repos"))
for repo in result.observation.repos:
    print(f"{repo['name']}: {repo['clone_url']}")

# Clone to workspace
result = git_env.step(GitAction(action_type="clone_repo", repo_name="OpenEnv"))
print(result.observation.output)  # Cloned to: /workspace/OpenEnv

# Execute git commands
result = git_env.step(GitAction(
    action_type="execute_git_command",
    command="status",
    working_dir="OpenEnv"
))
print(result.observation.output)

# Cleanup
git_env.close()

Setup and Running the Example

Complete setup (run these steps in order):

# 0. Configure environment variables
cp .env.example .env
# Edit .env and set your Gitea credentials if needed

# 1. Start shared Gitea service (one-time)
./scripts/setup_shared_gitea.sh

# 2. Migrate a test repository to Gitea (one-time)
docker exec openenv-gitea curl -X POST \
  http://localhost:3000/api/v1/repos/migrate \
  -u gitea:gitea123 \
  -H 'Content-Type: application/json' \
  -d '{
    "clone_addr": "https://github.com/huggingface/OpenEnv",
    "repo_name": "OpenEnv",
    "repo_owner": "gitea",
    "service": "github"
  }'

# 3. Build Docker images
docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
docker build -t git-env:latest -f envs/git_env/server/Dockerfile .

# 4. Install Python dependencies
uv pip install -e .

# 5. Run the example (loads credentials from .env)
python3 examples/local_git_env.py

Note:

Steps 1-3 are one-time setup
Make sure .env file exists with your Gitea credentials
After initial setup, you only need step 5 to run the example

Environment Details

Actions

GitAction: Unified action class for all Git operations

@dataclass
class GitAction(Action):
    action_type: str           # Operation type
    repo_name: str            # Repository name (for clone/execute)
    target_dir: Optional[str] # Target directory (for clone)
    command: str              # Git command (for execute)
    working_dir: str          # Working directory (for execute)

Supported action_type values:

“clone_repo” - Clone repository to workspace

GitAction(action_type="clone_repo", repo_name="OpenEnv")
GitAction(action_type="clone_repo", repo_name="OpenEnv", target_dir="custom-dir")

“list_repos” - List available repositories

GitAction(action_type="list_repos")

“execute_git_command” - Execute git command

GitAction(
    action_type="execute_git_command",
    command="status",
    working_dir="OpenEnv"
)

Observation

GitObservation: Contains results of Git operations

@dataclass
class GitObservation(Observation):
    success: bool          # Whether operation succeeded
    message: str           # Human-readable message
    output: str            # Command output or detailed result
    error: str             # Error message if failed
    repos: list[dict]      # List of repositories (for list_repos)

State

GitState: Tracks environment state

@dataclass
class GitState(State):
    episode_id: str           # Unique episode identifier
    step_count: int           # Number of steps taken
    gitea_ready: bool         # Whether Gitea is accessible
    workspace_path: str       # Path to workspace directory

Advanced: Task-Based Training

For RL training scenarios where you need fast resets to specific repository states, you can configure task-specific base states in the environment. This is done by setting environment variables before starting containers:

# Example: Configure tasks for your training setup
docker run \
  -e GITEA_URL=http://host.docker.internal:3000 \
  -e TASK_REPOS='{"bug_fix": ["my-repo", "abc123"], "feature": ["my-repo", "def456"]}' \
  git-env:latest

Then in your training code, environments automatically reset to the configured state.

See examples/local_git_env.py for complete working example.

Project Structure

git_env/
├── README.md                      # This file
├── __init__.py                    # Exports
├── models.py                      # Action, Observation, State definitions
├── client.py                      # GitEnv HTTP client
├── docker-compose.gitea.yml       # Shared Gitea service
└── server/
    ├── __init__.py
    ├── git_task_environment.py    # Task-optimized environment
    ├── app.py                     # FastAPI application
    └── Dockerfile                 # Lightweight container image

Troubleshooting

Gitea Not Ready

If environment can’t connect to Gitea:

Ensure Gitea is running: docker ps | grep gitea
Check Gitea URL in environment: GITEA_URL=http://gitea:3000
Verify network connectivity: docker network ls | grep openenv

Repository Not Found

Ensure repository is migrated to Gitea:

# List repos
curl -u gitea:gitea123 http://localhost:3000/api/v1/user/repos

Slow Clone/Reset

First clone is slower (~5-10s) - downloads from Gitea
Subsequent resets are fast (<1s) - just git operations
Use task-based mode with task_repos for optimal performance

Security Notes

Never commit .env file - it contains credentials (already in .gitignore)
Use .env.example as a template and create your own .env
Gitea credentials are for local development only
For production, use proper secret management (Docker secrets, k8s secrets, etc.)
All workspaces are isolated per container
Only public repositories supported (no private repo auth)

Update on GitHub