Git Integration Guide

Learn how to connect your GitHub repositories to TeamDay spaces, enabling your AI agents to work with version control.

Table of Contents

• What You'll Learn
• Prerequisites
• Understanding Git in TeamDay
• GitHub OAuth Setup
• Cloning Repositories
• Committing Changes
• Working with Branches
• Best Practices
• Troubleshooting

What You'll Learn

By the end of this guide, you'll know how to:

• ✅ Set up GitHub OAuth authentication
• ✅ Clone private repositories into spaces
• ✅ Let agents commit and push changes
• ✅ Manage branches and pull requests
• ✅ Configure Git credentials securely
• ✅ Handle merge conflicts

Time to complete: 15-20 minutes

Prerequisites

Before starting, ensure you have:

• ✅ A TeamDay account (Sign up guide)
• ✅ A space created (Space setup guide)
• ✅ An agent created (Agent guide)
• ✅ A GitHub account with repositories

Understanding Git in TeamDay

How Git Works in Spaces

TeamDay spaces have built-in Git support, allowing you to clone repositories, track changes, and sync with GitHub directly from the interface.

Each space can contain multiple Git repositories. When you clone a repo, it's placed in a subdirectory within your space, keeping your projects organized.

Space structure example:

my-space/
├── CLAUDE.md           # Space configuration
├── my-webapp/          # Cloned repository
│   ├── .git/
│   ├── src/
│   └── package.json
└── another-repo/       # Another cloned repository
    ├── .git/
    └── ...

Key Features

Version Control

• Full Git functionality in every space
• Commit, branch, merge, and rebase
• Complete history tracking

GitHub Integration

• OAuth authentication
• Clone private repositories
• Push changes back to GitHub
• Automatic credential management

Agent Capabilities

• Agents can read repository files
• Commit changes with meaningful messages
• Create and switch branches
• Push to remote repositories

GitHub OAuth Setup

Before you can clone private repositories, you need to connect your GitHub account to TeamDay.

Authorize GitHub Access

Step 1: Navigate to Space Settings

1. Open your space
2. Go to Settings tab
3. Click "Integrations" in the sidebar
4. Find "GitHub" section

Step 2: Connect GitHub

1. Click "Connect GitHub" button
2. You'll be redirected to GitHub
3. Review the permissions requested:
   • ✅ Read/write access to repositories
   • ✅ Read user profile
   • ✅ Access to private repositories
4. Click "Authorize TeamDay"

Step 3: Confirm Connection

After authorization:

• You'll be redirected back to TeamDay
• Status shows "GitHub Connected" with green checkmark
• Your GitHub username is displayed
• You can now clone private repositories

Permissions Granted:

Manage GitHub Connection

View Connection Status:

Settings → Integrations → GitHub

Shows:

• Connected username
• Last authenticated date
• Token expiration (90 days)
• Scopes granted

Disconnect GitHub:

1. Settings → Integrations → GitHub
2. Click "Disconnect"
3. Confirm disconnection

Reconnect GitHub:

If your token expires (after 90 days):

1. You'll see "GitHub Disconnected" warning
2. Click "Reconnect"
3. Re-authorize on GitHub

Token Refresh

GitHub tokens automatically refresh:

• Access token: 15 minutes
• Refresh token: 90 days

TeamDay handles this automatically. You'll only need to re-authorize if the refresh token expires.

Cloning Repositories

Clone Public Repository

Via UI:

1. Open your space → Files panel
2. Click "+" button in toolbar
3. Select "Clone Repository"
4. Enter repository URL:

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

5. (Optional) Specify branch (default: main)
6. (Optional) Specify destination directory
7. Click "Clone"

Via Agent:

Ask your agent to clone:

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

Agent: [Executes git clone command]

Via API:

curl -X POST "https://cc.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"
  }'

Clone Private Repository

Prerequisites:

• ✅ GitHub OAuth connected (see GitHub OAuth Setup)

Via UI:

1. Open space → Files panel
2. Click "+" → "Clone Repository"
3. Enter private repository URL:

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

4. If GitHub not connected:
   • You'll see prompt: "Connect GitHub to clone private repositories"
   • Click "Connect GitHub"
   • Complete OAuth flow
   • Return to clone modal
5. If GitHub connected:
   • Green checkmark shows "GitHub Connected"
   • Click "Clone"

Via Agent:

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

Agent: [Uses GitHub OAuth token to clone]

Via API:

curl -X POST "https://cc.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
  }'

Clone Progress

Watch clone progress:

In UI:

• Progress bar shows percentage
• Status updates: "Fetching objects...", "Resolving deltas..."
• Usually takes 5-30 seconds depending on repo size

In Terminal (if using agent):

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.

Via API - Poll status:

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

Response:

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

Git Panel

The Git panel appears at the top of the Files sidebar and shows the status of your space's root directory.

Panel States

No Git Repository

• Appears when the space root doesn't have Git initialized
• You can either:
  • Clone a repo using the + button (recommended)
  • Initialize Git in the space root to track loose files

Git Repository Active

• Shows the current branch name
• Displays change count (staged + unstaged + untracked)
• Shows ahead/behind indicators for remote sync status

Expanding the Panel

Click the Git panel header to expand it and see:

• Remote repository URL
• List of changed files (staged, modified, untracked)
• Commit and sync controls

Committing Changes

Viewing Git Status

Via UI - Git Panel:

1. Open space → Files panel
2. Expand Git Panel at top
3. View status:
   • Current branch name
   • Modified files count
   • Staged changes count
   • Ahead/behind indicators

Via Agent:

User: "Check git status"

Agent: [Executes: git status]

Output:
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

Via API:

curl -X POST "https://cc.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"
  }'

Staging Changes

Via UI:

1. Expand Git Panel
2. Review changed files
3. Options:
   • Stage All - Stage everything
   • Stage File - Click checkbox next to file
   • Unstage - Uncheck staged file

Via Agent:

User: "Stage all changes"

Agent: [Executes: git add .]

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

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

Selective Staging:

User: "Stage all TypeScript files except tests"

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

Creating Commits

Via UI:

1. Stage your changes (see above)
2. Enter commit message in text area:

   Add user validation to API endpoints
   
   

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

3. Click **"Commit"** button

![Screenshot](./images/git-integration/commit-ui.png)

**Via Agent:**

Agents can create commits with meaningful messages:

User: "Commit these changes with a good message"

Agent: 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"

**Via API:**

```bash
curl -X POST "https://cc.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\""
  }'

Commit Message Best Practices

Good commit messages:

✅ 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

Bad commit messages:

❌ update stuff
❌ fix
❌ wip
❌ asdfasdf
❌ changes

Format:

<type>: <subject>

<body>

<footer>

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• refactor: - Code restructuring
• test: - Add/update tests
• chore: - Maintenance tasks

Pushing to Remote

Via UI:

1. After committing, Git Panel shows "↑ 1" (commits ahead)
2. Click "Push" button
3. Changes are pushed to GitHub

Via Agent:

User: "Push my commits to GitHub"

Agent: [Executes: git push origin main]

Via API:

curl -X POST "https://cc.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"
  }'

First Push (Set Upstream):

git push -u origin main

TeamDay automatically sets upstream on first push.

Pulling Updates

Via UI:

1. Git Panel shows "↓ 2" (commits behind)
2. Click "Pull" button
3. Latest changes are fetched and merged

Via Agent:

User: "Pull the latest changes from GitHub"

Agent: [Executes: git pull origin main]

Via API:

curl -X POST "https://cc.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"
  }'

Viewing Commit History

Via UI:

1. Open space → History tab
2. View commits with:
   • Commit message
   • Author and date
   • Changed files
   • Diff view

Via Agent:

User: "Show recent commit history"

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

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

Via API:

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

Working with Branches

Creating Branches

Via Agent:

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

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

Via API:

curl -X POST "https://cc.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"
  }'

Switching Branches

Via Agent:

User: "Switch to the main branch"

Agent: [Executes: git checkout main]

Merging Branches

Via Agent:

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

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

Deleting Branches

Via Agent:

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

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

Adding a Remote

If you initialized Git locally and want to connect to a remote:

Via Agent:

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

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

Via API:

curl -X POST "https://cc.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"
  }'

Best Practices

1. Commit Early and Often

Do:

✅ Small, focused commits
✅ Commit after each logical change
✅ Easy to review and revert

Example mission:

Commit 1: Add user model
Commit 2: Add user validation
Commit 3: Add user API endpoints
Commit 4: Add user tests

Don't:

❌ One giant commit at end of day
❌ Mix unrelated changes
❌ Commit broken code

2. Write Meaningful Commit Messages

Good:

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

Bad:

updates
fix stuff
work in progress

3. Pull Before You Push

Always sync before pushing:

User: "Pull latest changes then push my commits"

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

Prevents merge conflicts and keeps history clean.

4. Use Branches for Features

Create feature branches:

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

Mission:

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

Agent: [Creates branch, implements feature]

User: "Merge to main when done"

Agent: [Merges and deletes branch]

5. Keep Main Branch Stable

Main branch rules:

• ✅ Always deployable
• ✅ All tests passing
• ✅ Code reviewed
• ✅ No WIP commits

Feature branch rules:

• ✅ Work in progress OK
• ✅ Experiment freely
• ✅ Squash before merging

6. Review Changes Before Committing

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

Agent: [Executes: git diff --staged]

Catch mistakes before they're committed.

7. Use .gitignore

Always ignore:

# Dependencies
node_modules/
.env
.env.local

# Build outputs
dist/
.next/

# Logs
*.log

# OS
.DS_Store

8. Protect Sensitive Data

Never commit:

• ❌ API keys or secrets
• ❌ Passwords
• ❌ Private keys
• ❌ Database credentials

Use instead:

• ✅ Environment variables
• ✅ TeamDay secrets
• ✅ .env files (in .gitignore)

Working with AI Agents

AI agents in your space can use Git commands directly.

What Agents Can Do

Read repository state:

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

Make commits:

User: "Commit these changes with a descriptive message"

Agent: [Analyzes changes, writes meaningful commit message]

Manage branches:

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

Sync with remote:

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

Agent Git Mission

Example: Add a feature

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

Agent:
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

CLAUDE.md Git Instructions

Add Git guidance to your CLAUDE.md:

## Git Mission

### Before Committing
1. Run tests: `bun test`
2. Check lint: `bun run lint`
3. Review changes: `git diff`

### Commit Message Format

## Troubleshooting

### "Not a git repository"

**Problem:** Space root doesn't have Git initialized

**Solutions:**

1. **Initialize Git:**

2. **Navigate to cloned repo:**

### Authentication Failed

**Problem:** Can't clone private repository

**Solutions:**

1. **Check GitHub connection:**
   - Settings → Integrations → GitHub
   - Should show "Connected" status

2. **Reconnect GitHub:**
   - Click "Disconnect"
   - Click "Connect"
   - Re-authorize

3. **Verify repository access:**
   - Go to GitHub.com
   - Check you have access to the repo
   - Verify repository URL is correct

### Clone Timeout

**Problem:** Large repository times out

**Solutions:**

1. **Shallow clone:**

2. **Clone specific branch:**

### Merge Conflicts

**Problem:** Conflicts when pulling or merging

**Solutions:**

1. **View conflicts:**

2. **Resolve conflicts:**

3. **Abort merge if needed:**

### Accidentally Committed Secrets

**Problem:** Committed API keys or passwords

**Solutions:**

1. **If not pushed yet:**

2. **If already pushed:**

**IMPORTANT:** Always rotate exposed secrets immediately!

### Push Rejected

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

**Solution:**

## Security Best Practices

### 1. Never Commit Secrets

**Add to .gitignore:**
```gitignore
.env
.env.local
.env.*.local
*.key
*.pem
secrets.json
credentials.json

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

const apiKey = process.env.API_KEY;

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

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