--- title: git_env Environment sdk: docker app_port: 8000 base_path: /web tags: - openenv - openenv-v2.1.0 --- # git_env Environment Space URL: `https://huggingface.co/spaces/openenv/git_env-v2-1-0` OpenEnv pinned ref: `v2.1.0` # 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 ```python 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): ```bash # 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/meta-pytorch/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 ```python @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 ```python 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 ```python GitAction(action_type="list_repos") ``` #### "execute_git_command" - Execute git command ```python GitAction( action_type="execute_git_command", command="status", working_dir="OpenEnv" ) ``` ### Observation **GitObservation**: Contains results of Git operations ```python @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 ```python @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: ```bash # 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`](../../../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: 1. Ensure Gitea is running: `docker ps | grep gitea` 2. Check Gitea URL in environment: `GITEA_URL=http://gitea:3000` 3. Verify network connectivity: `docker network ls | grep openenv` ### Repository Not Found Ensure repository is migrated to Gitea: ```bash # 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)