GitHub

What is GitHub integration?

GitHub integration automatically creates and manages repositories for your App2 projects. Every code change syncs to GitHub, giving you full version control, history, and the ability to clone and work locally.

What you get:

• Automatic repositories: Created for every project

• Code synchronization: All changes saved to GitHub

• Version control: Complete git history

• Local development: Clone and work on your machine

• Collaboration: Standard git workflows

• Backup: Your code is safe in GitHub

Two repository types:

• App2-managed: Hosted in App2's GitHub organization (default, all tiers)

• User-owned: Hosted in your GitHub account/organization (Pro feature)

Repository types

Choose where your code lives.

App2-managed repositories

Default for all users—repositories hosted in App2's GitHub organization.

Characteristics:

• Created automatically for every project

• Available to all tiers (Free, Pro, Lifetime Pro)

• No GitHub connection required

• Full access to clone and fork

• You can export the project, but you cannot access the GitHub repository directly

Best for:

• Getting started quickly

• Free tier users

• Learning and experiments

• When you don't need your own GitHub org

User-owned repositories

Migrate your repository to your own GitHub account or organization (Pro feature).

Characteristics:

• Hosted at github.com/your-org/your-project

• Requires Pro subscription ($25/month)

• Your organization, your control

• Connect custom domains via Vercel

• Professional branding

• Team collaboration in your org

Best for:

• Professional projects

• Client work

• Company/team projects

• When you need your own GitHub org

Comparison

Tip: Start with App2-managed repositories. Migrate to user-owned when you need professional branding or custom domains.

Prerequisites

For App2-managed repositories:

• App2 account (any tier)

• Nothing else—works automatically

For user-owned repositories:

• GitHub account

• Pro subscription ($25/month)

• GitHub organization (or use personal account)

• Workspace owner or admin role

Setup steps

For App2-managed repositories

No setup required.

When you create a project, App2 automatically:

1. Creates a GitHub repository

2. Syncs your code

3. Provides repository URL

4. Enables git operations

That's it—you're done!

For user-owned repositories (Pro)

Migrate your repository to your own GitHub organization.

Step 1: Connect GitHub App

1. Go to Workspace Settings → Integrations → GitHub

2. Click "Connect GitHub"

3. Redirected to GitHub for authorization

4. Select organizations to grant access

5. Click "Install & Authorize"

6. Redirected back to App2

Your GitHub account is now connected.

Step 2: Link project to your GitHub

1. Open your project

2. Go to Project Settings → General → GitHub Repository

3. Find "Link Your Own GitHub" section

4. Select your GitHub organization from dropdown

5. Click "Migrate repository"

6. Wait for migration (30-60 seconds)

7. Page refreshes automatically

Your repository is now at github.com/your-org/project-slug.

Using GitHub integration

Automatic code synchronization

Every code change the AI makes is automatically committed to GitHub.

What gets synced:

• All file changes

• New files created

• Deleted files

• Package.json updates

• Configuration changes

Commit messages:

• Auto-generated based on changes

• Include file names and operation types

• Timestamped for history

Sync frequency:

• Immediately after AI completes code generation

• Before deployments

• After significant changes

Accessing your repository

View repository:

• Check Quick Actions → Integrations → GitHub

• Or Project Settings → General → GitHub Repository

• Shows repository URL and status

Clone repository:

git clone https://github.com/org-name/project-slug.git
cd project-slug

Work locally:

• Clone repository to your machine

• Make changes in your favorite editor

• Push changes back to GitHub

• App2 syncs changes automatically

Linking your own GitHub (Pro)

Migrate from App2-managed to user-owned repository.

Requirements:

• Pro subscription

• GitHub App connected

• Project in Ready status

Migration process:

1. App2 creates new repo in your organization

2. Copies all code and history

3. Updates project to use new repo

4. Old App2-managed repo archived (not deleted)

What stays the same:

• All code and files

• Git history preserved

• Sandbox continues working

• Chat sessions unaffected

What changes:

• Repository URL (becomes → your-org/*)

• Repository ownership

• Can now use custom domains (Vercel)

Project freeze protection

App2 protects your projects when GitHub access is revoked or lost.

What is project freezing?

When GitHub access is lost, App2 "freezes" affected projects to prevent data loss or inconsistencies.

Frozen projects cannot:

• Generate new code

• Make file changes

• Deploy to production

• Sync to GitHub

Frozen projects can:

• View existing code

• Read chat history

• Access project settings

• See the freeze reason

When projects freeze

Projects freeze when:

• GitHub App installation revoked

• GitHub App installation suspended

• Repository deleted from GitHub

• Repository archived

• Organization deleted

• Organization access removed

Automatic protection:

• Prevents code generation errors

• Stops broken git operations

• Protects data integrity

• Clear messaging about issue

Unfreezing projects

Projects unfreeze automatically when:

• GitHub App reinstalled

• Repository unarchived

• Installation reconnected

• Access restored

How to unfreeze:

1. Check freeze reason in project banner

2. Reconnect GitHub App (if revoked)

3. Unarchive repository (if archived)

4. Restore organization access (if removed)

5. Project unfreezes immediately

Manual unfreeze: Contact support if automatic unfreeze doesn't work.

Managing organizations

Viewing connected organizations

See all GitHub organizations connected to your workspace.

Where to view:

1. Go to Workspace Settings → Integrations → GitHub

2. Lists all connected organizations

3. Shows installation status for each

Organization status:

• Active (green): Working properly

• Suspended (yellow): Needs attention

• Removed (red): No longer accessible

Reconnecting GitHub

If installation is suspended or removed, reconnect it.

How to reconnect:

1. Go to Workspace Settings → Integrations → GitHub

2. Find organization with "Suspended" or "Removed" status

3. Click "Reconnect" or "Connect GitHub"

4. Authorize on GitHub again

5. Status updates to "Active"

Frozen projects unfreeze automatically after successful reconnection.

Removing organizations

Remove GitHub organizations you no longer need.

How to remove:

1. Revoke App2 GitHub App access in GitHub settings

2. Organization shows as "Removed" in App2

3. Projects using this org will freeze

4. Reconnect or migrate projects to another org

Best practices

Repository management

For App2-managed repos:

• Keep them for learning and experiments

• Free tier perfect for public projects

• Easy to get started

• Migrate to user-owned when you need full control and ownership

For user-owned repos:

• Use for client work

• Professional project organization

• Team collaboration in your org

• Required for custom domains

Security

Protect your repositories:

• Review GitHub App permissions periodically

• Monitor repository access

• Use private repositories for sensitive code

• Enable branch protection (in GitHub)

• Require code review for important projects

Workflow tips

Local development:

# Clone repository
git clone https://github.com/your-org/project.git

# Create branch
git checkout -b feature/new-feature

# Make changes locally
# ... edit files ...

# Commit and push
git add .
git commit -m "Add new feature"
git push origin feature/new-feature

Syncing with App2:

• App2 pulls latest changes automatically

• Work in App2 or locally

• Changes sync both ways

• Use git for advanced workflows

Troubleshooting

Can't connect GitHub

Issue: GitHub connection fails or redirects don't work.

Solutions:

1. Check you're logged into GitHub in same browser

2. Allow pop-ups from App2.dev

3. Try connecting in incognito/private mode

4. Clear browser cache

5. Verify GitHub account has proper permissions

Project frozen after GitHub changes

Issue: "Project Frozen" banner appears, can't make changes.

Solutions:

1. Read freeze reason in banner

2. Click "Reconnect" link to go to settings

3. Reinstall GitHub App if revoked

4. Unarchive repository if archived

5. Restore organization access if removed

6. Project unfreezes automatically when access restored

Can't migrate to user-owned repository

Issue: "Migrate repository" button disabled or not showing.

Solutions:

1. Verify you have Pro subscription

2. Check GitHub App is connected

3. Ensure you're workspace owner/admin

4. Confirm project status is Ready (not Scaffolding or Building)

5. Select a GitHub organization from dropdown

Repository not syncing

Issue: Code changes in App2 not appearing in GitHub.

Solutions:

1. Check GitHub repository exists (not deleted)

2. Verify project isn't frozen

3. Check GitHub App installation is active

4. Wait a few minutes for sync

5. Restart sandbox if needed

Multiple organizations showing

Issue: Seeing organizations you didn't expect.

Solution: This is normal. GitHub App shows all organizations where you granted access during installation. You can install App2 on multiple organizations.

FAQ

Do I need to connect GitHub?

No, but it's automatic for all projects. Every project gets a GitHub repository by default—no action needed on your part.

Can Free tier users use GitHub?

Yes. Free tier gets App2-managed repositories automatically. User-owned repositories require Pro subscription.

What's the difference between App2-managed and user-owned repos?

App2-managed: Hosted internally in App2's GitHub organization, available on all tiers, automatic setup.

User-owned: Hosted at github.com/your-org/*, requires Pro, more control, needed for custom domains.

Can I switch from App2-managed to user-owned?

Yes. Go to Project Settings → GitHub Repository → Migrate repository. Requires Pro subscription. Migration copies all code and history.

What if I revoke GitHub App access?

Projects using that GitHub organization will freeze. You can't make code changes until you reinstall the GitHub App and restore access.

Can I use the same GitHub organization for multiple projects?

Yes. One GitHub organization can host repositories for multiple App2 projects. Each project gets its own repository.

Will my repository be deleted if I delete my project?

You choose during project deletion. You can keep the GitHub repository (code preserved) or delete it entirely.

Can I make my repository private?

Yes. Repository visibility matches your project visibility. Make your project private (Pro feature) and the GitHub repo becomes private too.

Can team members access the GitHub repository?

App2-managed: Public projects = public repos. Private projects = only workspace members.

User-owned: Access controlled by your GitHub organization permissions.

How do I add collaborators to my repository?

App2-managed: Invite members to your App2 workspace.

User-owned: Manage collaborators in your GitHub organization settings.

Related links

• Projects - Understanding projects

• Workspaces - Team collaboration

• Private Projects - Public vs private

• Custom Domains - Requires user-owned repo

• Plans and Credits - Pro subscription

• Getting Started