Guía de Integración con Git

Aprende cómo conectar tus repositorios de GitHub a espacios de TeamDay, habilitando tus agentes de IA para trabajar con control de versiones.

Tabla de Contenidos

Lo Que Aprenderás
Requisitos Previos
Entendiendo Git en TeamDay
Configuración de OAuth con GitHub
Clonando Repositorios
Confirmando Cambios
Trabajando con Ramas
Mejores Prácticas
Solución de Problemas

Lo Que Aprenderás

Al final de esta guía, sabrás cómo:

✅ Configurar autenticación OAuth con GitHub
✅ Clonar repositorios privados en espacios
✅ Permitir que los agentes confirmen y empujen cambios
✅ Gestionar ramas y solicitudes de extracción
✅ Configurar credenciales de Git de forma segura
✅ Manejar conflictos de fusión

Tiempo para completar: 15-20 minutos

Requisitos Previos

Antes de comenzar, asegúrate de tener:

✅ Una cuenta de TeamDay (Guía de registro)
✅ Un espacio creado (Guía de configuración de espacio)
✅ Un agente creado (Guía de agentes)
✅ Una cuenta de GitHub con repositorios

Entendiendo Git en TeamDay

Cómo Funciona Git en Espacios

Los espacios de TeamDay tienen soporte integrado de Git, permitiéndote clonar repositorios, rastrear cambios y sincronizar con GitHub directamente desde la interfaz.

Cada espacio puede contener múltiples repositorios Git. Cuando clonas un repo, se coloca en un subdirectorio dentro de tu espacio, manteniendo tus proyectos organizados.

Ejemplo de estructura del espacio:

my-space/
├── CLAUDE.md           # Configuración del espacio
├── my-webapp/          # Repositorio clonado
│   ├── .git/
│   ├── src/
│   └── package.json
└── another-repo/       # Otro repositorio clonado
    ├── .git/
    └── ...

Características Clave

Control de Versiones

Funcionalidad completa de Git en cada espacio
Confirmar, ramificar, fusionar y rebasar
Rastreo completo del historial

Integración con GitHub

Autenticación OAuth
Clonar repositorios privados
Empujar cambios de vuelta a GitHub
Gestión automática de credenciales

Capacidades de Agentes

Los agentes pueden leer archivos del repositorio
Confirmar cambios con mensajes significativos
Crear y cambiar ramas
Empujar a repositorios remotos

Screenshot

Configuración de OAuth con GitHub

Antes de que puedas clonar repositorios privados, necesitas conectar tu cuenta de GitHub a TeamDay.

Autoriza Acceso a GitHub

Paso 1: Navega a Configuración del Espacio

Abre tu espacio
Ve a la pestaña Configuración
Haz clic en “Integraciones” en la barra lateral
Encuentra la sección “GitHub”

Screenshot

Paso 2: Conecta GitHub

Haz clic en el botón “Conectar GitHub”
Serás redirigido a GitHub
Revisa los permisos solicitados:
- ✅ Acceso lectura/escritura a repositorios
- ✅ Leer perfil de usuario
- ✅ Acceder a repositorios privados
Haz clic en “Autorizar TeamDay”

Screenshot

Paso 3: Confirma Conexión

Después de la autorización:

Serás redirigido de vuelta a TeamDay
El estado muestra “GitHub Conectado” con marca de verificación verde
Tu nombre de usuario de GitHub se muestra
Ahora puedes clonar repositorios privados

Screenshot

Permisos Otorgados:

Permiso	Propósito
`repo`	Acceso lectura/escritura a repositorios
`read:user`	Leer tu perfil de GitHub
`mission`	Desencadenar Acciones de GitHub (opcional)

Gestiona Conexión de GitHub

Ver Estado de Conexión:

Configuración → Integraciones → GitHub

Muestra:

Nombre de usuario conectado
Fecha de última autenticación
Expiración del token (90 días)
Alcances otorgados

Desconectar GitHub:

Configuración → Integraciones → GitHub
Haz clic en “Desconectar”
Confirma desconexión

Reconectar GitHub:

Si tu token expira (después de 90 días):

Verás advertencia de “GitHub Desconectado”
Haz clic en “Reconectar”
Re-autoriza en GitHub

Actualización de Token

Los tokens de GitHub se actualizan automáticamente:

Token de acceso: 15 minutos
Token de actualización: 90 días

TeamDay maneja esto automáticamente. Solo necesitarás re-autorizar si el token de actualización expira.

Clonando Repositorios

Clonar Repositorio Público

Vía UI:

Abre tu espacio → Panel Archivos
Haz clic en el botón ”+” en la barra de herramientas
Selecciona “Clonar Repositorio”

Ingresa URL del repositorio:

https://github.com/username/public-repo.git

(Opcional) Especifica rama (predeterminado: main)
(Opcional) Especifica directorio de destino
Haz clic en “Clonar”

Screenshot

Vía Agente:

Pide a tu agente que clone:

Usuario: "Clone the repository https://github.com/user/repo.git"

Agente: [Executes git clone command]

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123/init" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gitUrl": "https://github.com/username/repo.git",
    "gitBranch": "main",
    "directory": "my-project"
  }'

Clonar Repositorio Privado

Requisitos Previos:

✅ GitHub OAuth conectado (ver Configuración de OAuth con GitHub)

Vía UI:

Abre espacio → Panel Archivos
Haz clic en ”+” → “Clonar Repositorio”

Ingresa URL del repositorio privado:

https://github.com/username/private-repo.git

Si GitHub no está conectado:
- Verás solicitud: “Conecta GitHub para clonar repositorios privados”
- Haz clic en “Conectar GitHub”
- Completa flujo OAuth
- Vuelve al modal de clon
Si GitHub está conectado:
- La marca de verificación verde muestra “GitHub Conectado”
- Haz clic en “Clonar”

Screenshot

Vía Agente:

Usuario: "Clone my private repository https://github.com/myorg/private-api.git"

Agente: [Uses GitHub OAuth token to clone]

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/spaces/s-abc123/init" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gitUrl": "https://github.com/username/private-repo.git",
    "useGitHubAuth": true
  }'

Progreso de Clon

Ve el progreso del clon:

En UI:

La barra de progreso muestra porcentaje
Actualizaciones de estado: “Fetching objects…”, “Resolving deltas…”
Generalmente toma 5-30 segundos dependiendo del tamaño del repo

En Terminal (si usas agente):

Cloning into 'repo-name'...
remote: Enumerating objects: 1234, done.
remote: Counting objects: 100% (1234/1234), done.
remote: Compressing objects: 100% (890/890), done.
Receiving objects: 100% (1234/1234), 5.67 MiB | 8.90 MiB/s, done.
Resolving deltas: 100% (456/456), done.

Vía API - Encuesta el estado:

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-abc123/environment" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Respuesta:

{
  "status": "cloning",
  "progress": 67,
  "message": "Resolving deltas..."
}

Panel de Git

El panel de Git aparece en la parte superior de la barra lateral de Archivos y muestra el estado de tu directorio raíz del espacio.

Estados del Panel

Sin Repositorio Git

Aparece cuando la raíz del espacio no tiene Git inicializado
Puedes:
- Clonar un repo usando el botón + (recomendado)
- Inicializar Git en la raíz del espacio para rastrear archivos sueltos

Repositorio Git Activo

Muestra el nombre de la rama actual
Muestra recuento de cambios (staged + unstaged + untracked)
Muestra indicadores adelante/atrás para estado de sincronización remota

Expandiendo el Panel

Haz clic en el encabezado del panel de Git para expandirlo y ver:

URL del repositorio remoto
Lista de archivos cambiados (staged, modified, untracked)
Controles de confirmación y sincronización

Confirmando Cambios

Ver Estado de Git

Vía UI - Panel de Git:

Abre espacio → Panel Archivos
Expande Panel de Git en la parte superior
Ve el estado:
- Nombre de rama actual
- Recuento de archivos modificados
- Recuento de cambios staged
- Indicadores adelante/atrás

Screenshot

Vía Agente:

Usuario: "Check git status"

Agente: [Executes: git status]

Salida:
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  modified:   src/api/users.ts
  modified:   README.md

Untracked files:
  src/utils/helpers.ts

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git status --short"
  }'

Organizando Cambios

Vía UI:

Expande Panel de Git
Revisa archivos cambiados
Opciones:
- Organizar Todo - Organiza todo
- Organizar Archivo - Haz clic en casilla de verificación junto a archivo
- Desorganizar - Desmarca archivo organizado

Screenshot

Vía Agente:

Usuario: "Stage all changes"

Agente: [Executes: git add .]

Usuario: "Stage only the src/api/users.ts file"

Agente: [Executes: git add src/api/users.ts]

Organización Selectiva:

Usuario: "Stage all TypeScript files except tests"

Agente: [Executes: git add src/**/*.ts && git reset src/**/*.test.ts]

Creando Confirmaciones

Vía UI:

Organiza tus cambios (ver arriba)

Ingresa mensaje de confirmación en área de texto:

Add user validation to API endpoints

- Implement email validation
- Add password strength checks
- Return detailed error messages

Haz clic en el botón “Confirmar”

Screenshot

Vía Agente:

Los agentes pueden crear confirmaciones con mensajes significativos:

Usuario: "Commit these changes with a good message"

Agente: [Analyzes changes, creates commit]

Executes: git commit -m "Add input validation to user API

- Implement email format validation
- Add password strength requirements
- Return user-friendly error messages
- Add unit tests for validation logic"

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git commit -m \"Add user validation\""
  }'

Mejores Prácticas de Mensajes de Confirmación

Buenos mensajes de confirmación:

✅ Add user authentication endpoints

✅ Fix SQL injection vulnerability in user query

✅ Refactor database connection pooling
- Use connection pool for better performance
- Add connection timeout configuration
- Implement automatic retry logic

✅ Update dependencies to latest versions
- React 18.2.0 → 18.3.0
- TypeScript 5.0.0 → 5.3.0
- Fix breaking changes in API

Malos mensajes de confirmación:

❌ update stuff
❌ fix
❌ wip
❌ asdfasdf
❌ changes

Formato:

<type>: <subject>

<body>

<footer>

Tipos:

feat: - Nueva característica
fix: - Corrección de error
docs: - Documentación
refactor: - Reestructuración de código
test: - Añadir/actualizar pruebas
chore: - Tareas de mantenimiento

Empujando a Remoto

Vía UI:

Después de confirmar, el Panel de Git muestra ”↑ 1” (confirmaciones adelante)
Haz clic en el botón “Empujar”
Los cambios se empujan a GitHub

Screenshot

Vía Agente:

Usuario: "Push my commits to GitHub"

Agente: [Executes: git push origin main]

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git push origin main"
  }'

Primer Empuje (Establecer Upstream):

git push -u origin main

TeamDay establece automáticamente upstream en el primer empuje.

Tirando Actualizaciones

Vía UI:

El Panel de Git muestra ”↓ 2” (confirmaciones atrás)
Haz clic en el botón “Tirar”
Los cambios más recientes se recuperan y fusionan

Screenshot

Vía Agente:

Usuario: "Pull the latest changes from GitHub"

Agente: [Executes: git pull origin main]

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git pull origin main"
  }'

Ver Historial de Confirmaciones

Vía UI:

Abre espacio → Pestaña Historial
Ve confirmaciones con:
- Mensaje de confirmación
- Autor y fecha
- Archivos cambiados
- Vista de diff

Screenshot

Vía Agente:

Usuario: "Show recent commit history"

Agente: [Executes: git log --oneline -10]

Salida:
abc1234 Add user validation
def5678 Fix authentication bug
ghi9012 Update dependencies
...

Vía API:

curl -X GET "https://us.teamday.ai/api/v1/spaces/s-space123/git/log" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Trabajando con Ramas

Creando Ramas

Vía Agente:

Usuario: "Create a new branch called 'feature/add-auth'"

Agente: [Executes: git checkout -b feature/add-auth]

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git checkout -b feature/add-auth"
  }'

Cambiando de Rama

Vía Agente:

Usuario: "Switch to the main branch"

Agente: [Executes: git checkout main]

Fusionando Ramas

Vía Agente:

Usuario: "Merge feature/add-auth into main"

Agente: [Executes sequence:
  git checkout main
  git merge feature/add-auth
]

Eliminando Ramas

Vía Agente:

Usuario: "Delete the feature/add-auth branch"

Agente: [Executes: git branch -d feature/add-auth]

Añadiendo un Remoto

Si inicializaste Git localmente y quieres conectar a un remoto:

Vía Agente:

Usuario: "Add Git remote: git remote add origin https://github.com/user/repo.git"

Agente: [Executes: git remote add origin https://github.com/user/repo.git]

Vía API:

curl -X POST "https://us.teamday.ai/api/v1/devenv/org-abc/s-space123/exec" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "git remote add origin https://github.com/user/repo.git"
  }'

Mejores Prácticas

1. Confirma Temprano y Frecuentemente

Haz:

✅ Confirmaciones pequeñas y enfocadas
✅ Confirma después de cada cambio lógico
✅ Fácil de revisar y revertir

Ejemplo de misión:

Confirmación 1: Add user model
Confirmación 2: Add user validation
Confirmación 3: Add user API endpoints
Confirmación 4: Add user tests

No Hagas:

❌ Una confirmación gigante al final del día
❌ Mezclar cambios no relacionados
❌ Confirmar código roto

2. Escribe Mensajes de Confirmación Significativos

Bueno:

feat: Add JWT authentication to user API

- Implement token generation on login
- Add middleware to verify tokens
- Include refresh token logic
- Add tests for auth flow

Malo:

updates
fix stuff
work in progress

3. Tira Antes de Empujar

Siempre sincroniza antes de empujar:

Usuario: "Pull latest changes then push my commits"

Agente: [Executes:
  git pull origin main
  git push origin main
]

Previene conflictos de fusión e historial limpio.

4. Usa Ramas para Características

Crea ramas de características:

main (stable)
  ├── feature/add-auth (new feature)
  ├── feature/user-profile (another feature)
  └── hotfix/login-bug (urgent fix)

Misión:

Usuario: "Create branch feature/add-auth and implement authentication"

Agente: [Creates branch, implements feature]

Usuario: "Merge to main when done"

Agente: [Merges and deletes branch]

5. Mantén Rama Main Estable

Reglas de rama main:

✅ Siempre desplegable
✅ Todas las pruebas pasando
✅ Código revisado
✅ No confirmaciones WIP

Reglas de rama de característica:

✅ Trabajo en progreso OK
✅ Experimenta libremente
✅ Aplasta antes de fusionar

6. Revisa Cambios Antes de Confirmar

Usuario: "Show me what changes I'm about to commit"

Agente: [Executes: git diff --staged]

Atrapa errores antes de que se confirmen.

7. Usa .gitignore

Siempre ignora:

# Dependencias
node_modules/
.env
.env.local

# Salida de compilación
dist/
.next/

# Logs
*.log

# OS
.DS_Store

8. Protege Datos Sensibles

Nunca confirmes:

❌ Claves de API o secretos
❌ Contraseñas
❌ Claves privadas
❌ Credenciales de base de datos

Usa en su lugar:

✅ Variables de entorno
✅ Secretos de TeamDay
✅ Archivos .env (en .gitignore)

Trabajando con Agentes de IA

Los agentes de IA en tu espacio pueden usar comandos Git directamente.

Qué Pueden Hacer los Agentes

Leer estado del repositorio:

Usuario: "What files have changed?"
Usuario: "Show me the last 5 commits"
Usuario: "Check if we're ahead of remote"

Hacer confirmaciones:

Usuario: "Commit these changes with a descriptive message"

Agente: [Analyzes changes, writes meaningful commit message]

Gestionar ramas:

Usuario: "Create a feature branch for authentication"
Usuario: "Merge my feature branch to main"
Usuario: "Delete old feature branches"

Sincronizar con remoto:

Usuario: "Pull latest changes"
Usuario: "Push my commits to GitHub"

Misión de Git del Agente

Ejemplo: Añadir una característica

Usuario: "Implement user authentication, commit, and push"

Agente:
1. Creates feature branch
2. Implements authentication code
3. Writes tests
4. Commits with message: "Add JWT authentication"
5. Pushes to GitHub
6. Reports completion

Instrucciones de Git de CLAUDE.md

Añade orientación de Git a tu CLAUDE.md:

## Misión de Git

### Antes de Confirmar
1. Ejecuta pruebas: `bun test`
2. Verifica lint: `bun run lint`
3. Revisa cambios: `git diff`

### Formato de Mensaje de Confirmación

```

Tipos: feat, fix, docs, refactor, test, chore

Nombrado de Ramas

feature/* - New features
fix/* - Bug fixes
hotfix/* - Urgent production fixes

Antes de Empujar

Tira lo más reciente: git pull origin main
Resuelve conflictos si hay
Ejecuta pruebas de nuevo
Empuja: git push origin <branch>


## Solución de Problemas

### "No es un repositorio git"

**Problema:** La raíz del espacio no tiene Git inicializado

**Soluciones:**

1. **Inicializa Git:**

Usuario: “Initialize git in this space”

Agente: [Executes: git init]


2. **Navega a repo clonado:**

cd my-webapp/ git status


### Falló la Autenticación

**Problema:** No puedes clonar repositorio privado

**Soluciones:**

1. **Verifica conexión de GitHub:**
   - Configuración → Integraciones → GitHub
   - Debe mostrar estado "Conectado"

2. **Reconecta GitHub:**
   - Haz clic en "Desconectar"
   - Haz clic en "Conectar"
   - Re-autoriza

3. **Verifica acceso al repositorio:**
   - Ve a GitHub.com
   - Verifica que tengas acceso al repo
   - Verifica que la URL del repositorio es correcta

### Tiempo Agotado de Clon

**Problema:** El repositorio grande agota el tiempo

**Soluciones:**

1. **Clon superficial:**

Usuario: “Clone with —depth 1 to speed it up”

Agente: [Executes: git clone —depth 1 ]


2. **Clon de rama específica:**

Usuario: “Clone only the main branch”

Agente: [Executes: git clone —single-branch -b main ]


### Conflictos de Fusión

**Problema:** Los conflictos cuando tiras o fusionas

**Soluciones:**

1. **Ver conflictos:**

Usuario: “Show me the merge conflicts”

Agente: [Executes: git status]


2. **Resuelve conflictos:**

Usuario: “Open the conflicted file and help me resolve it”

Agente: [Shows conflict markers, suggests resolution]


3. **Aborta fusión si es necesario:**

Usuario: “Abort this merge”

Agente: [Executes: git merge —abort]


### Accidentalmente Comprometiste Secretos

**Problema:** Confirmaste claves de API o contraseñas

**Soluciones:**

1. **Si no empujaste aún:**

Usuario: “Remove the last commit and unstage .env file”

Agente: [Executes: git reset HEAD~1 git reset .env ]


2. **Si ya empujaste:**

Usuario: “I accidentally committed secrets in .env”

Agente:

Adds .env to .gitignore
Removes .env from git: git rm —cached .env
Commits removal
Pushes changes
Recommends rotating the exposed secrets


**IMPORTANTE:** ¡Siempre rota secretos expuestos inmediatamente!

### Empuje Rechazado

**Problema:** `! [rejected] main -> main (non-fast-forward)`

**Solución:**

Usuario: “Pull with rebase then push”

Agente: [Executes: git pull —rebase origin main git push origin main ]


## Mejores Prácticas de Seguridad

### 1. Nunca Confirmes Secretos

**Añade a .gitignore:**
```ini
.env
.env.local
.env.*.local
*.key
*.pem
secrets.json
credentials.json

2. Usa Variables de Entorno

Almacena en configuración del espacio de TeamDay:

DATABASE_URL=postgresql://...
API_KEY=sk-...

Referencia en código:

const apiKey = process.env.API_KEY;

3. Rota Tokens de GitHub

Los tokens expiran después de 90 días
TeamDay notifica antes de expiración
Reconecta prontamente cuando se solicite

4. Revisa Historial de Confirmaciones

Antes de empujar, revisa:

Usuario: "Show me what I'm about to push"

Agente: [Executes: git log origin/main..HEAD]

5. Usa Protección de Rama

En GitHub:

Habilita protección de rama para main
Requiere revisiones de solicitud de extracción
Requiere verificaciones de estado

Próximos Pasos

Ahora que tienes integración con Git configurada:

1. Instala Complementos MCP

Añade herramientas para extender capacidades del agente
Guía: Complementos MCP

2. Configura Automatización

Programa operaciones de Git
Guía: Automatización

3. Crea Misiones

Construye tuberías CI/CD
Guía: Misiones

4. Uso Avanzado de Git

Aprende sobre rebasar, cherry-picking y más
Guía: [Git Avanzado

Recursos de Aprendizaje

API de OAuth de GitHub - Referencia de autenticación
[API de Espacios - Gestión de espacios
[Operaciones de Archivos - Gestión de archivos avanzada
[Seguridad - Asegura tus misiones

¡Feliz control de versiones! 🚀