GitHub - Kleap Documentation

Push your Kleap app code to GitHub for version control, backup, and code ownership.

Why GitHub?

Version control - Track every change with Git
Backup - Code stored safely in the cloud
Collaboration - Work with developers
Two-way sync - Changes flow both directions automatically
Portability - Own and take your Astro source code anywhere

GitHub is for backup, code ownership, and two-way sync — it is not how your site goes live. Kleap deploys your app automatically to Kleap’s global edge at {your-app}.kleap.io whenever you publish. Pushing to GitHub does not deploy anything.

Connecting GitHub

One-Time Setup

Go to Settings > GitHub
Click Connect GitHub
Authorize Kleap in the popup
Select repositories access

Permissions Requested

Read your profile
Create repositories
Push to repositories
Read repository contents

We only access repositories you explicitly connect. Your other repos remain private.

Pushing Code to GitHub

Create New Repository

Open your app
Go to Settings > GitHub
Click Create Repository
Enter repository name
Choose public or private
Click Create & Push

Connect Existing Repository

Open your app
Go to Settings > GitHub
Click Connect Repository
Select from your repositories
Confirm connection

Connecting to an existing repo will overwrite its contents. Make sure it’s empty or a backup exists.

Syncing Changes

Sync works in both directions: push to GitHub and Kleap syncs the changes in, and changes made in Kleap are pushed back to GitHub. A last-commit-sha guard prevents sync loops between the two sides.

Push to GitHub

After making changes in Kleap:

Go to Settings > GitHub
Click Push Changes
Enter a commit message (optional)
Changes are pushed to your repo

Auto-Push

Enable automatic syncing:

Go to Settings > GitHub
Toggle Auto-push on publish
Every publish also pushes to GitHub

Repository Structure

Your GitHub repo contains the full Astro project — an Astro 5 static site with Tailwind v4, React 19 islands, and TypeScript:

your-app/
├── src/
│   ├── pages/            # .astro pages and routes
│   ├── components/       # .astro and .tsx (React island) components
│   ├── layouts/
│   │   └── Base.astro    # Shared page layout
│   └── styles/
│       └── global.css    # Tailwind v4 styles
├── public/               # Static assets
├── astro.config.mjs      # Astro config
├── package.json          # Dependencies
└── tsconfig.json         # TypeScript config

Working with Developers

Push your code to GitHub
Share the repository URL
Developer clones and runs locally:

git clone https://github.com/you/your-app
cd your-app
npm install
npm run dev

Merge Developer Changes

When a developer pushes changes:

Go to Settings > GitHub
Click Pull Changes
Changes are synced to Kleap

Manual merges may be needed if both sides have changes. Advanced Git knowledge helps here.

Branches

Default Branch

Kleap works with your default branch (usually main or master).

Feature Branches

For experimental changes:

Developer creates branch locally
Makes changes and commits
Creates pull request
Merge to main when ready
Pull changes into Kleap

GitHub Actions

Your repository can use GitHub Actions for:

Automated testing - Run tests on push
Code quality - Lint and format checks
Build checks - Verify the Astro build passes

GitHub Actions run inside GitHub only. They don’t publish your Kleap site — deployment stays automatic through Kleap (to Kleap’s global edge at {your-app}.kleap.io).

Example Workflow

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm run build

Private vs Public

Type	Visibility	Use Case
Private	Only you and collaborators	Client projects, proprietary code
Public	Anyone can view	Open source, portfolios

Disconnecting GitHub

To disconnect:

Go to Settings > GitHub
Click Disconnect

Your repository remains on GitHub. Only the Kleap connection is removed.

Troubleshooting

Push failed

Check your GitHub connection is active
Ensure you have write access to the repo
Try disconnecting and reconnecting

Merge conflicts

Pull changes before pushing
Resolve conflicts manually if needed
Consider using a developer for complex merges

Repository not showing

Ensure you granted access during OAuth
Go to GitHub settings and update Kleap’s permissions
Try reconnecting your account

Large files rejected

GitHub has a 100MB file limit
Use Git LFS for large assets
Consider using a CDN for large images/videos

Best Practices

Push regularly

Don’t wait too long between pushes. Regular backups are safer.

Write good commits

Describe what changed in commit messages for future reference.

Use private repos

Keep client work and proprietary code in private repositories.

Review before merge

Always review developer changes before pulling into Kleap.

Version History

Use Kleap’s built-in version history alongside GitHub

​Why GitHub?

​Connecting GitHub

​One-Time Setup

​Permissions Requested

​Pushing Code to GitHub

​Create New Repository

​Connect Existing Repository

​Syncing Changes

​Push to GitHub

​Auto-Push

​Repository Structure

​Working with Developers

​Share with a Developer

​Merge Developer Changes

​Branches

​Default Branch

​Feature Branches

​GitHub Actions

​Example Workflow

​Private vs Public

​Disconnecting GitHub

​Troubleshooting

​Best Practices

Push regularly

Write good commits

Use private repos

Review before merge

Version History

Why GitHub?

Connecting GitHub

One-Time Setup

Permissions Requested

Pushing Code to GitHub

Create New Repository

Connect Existing Repository

Syncing Changes

Push to GitHub

Auto-Push

Repository Structure

Working with Developers

Share with a Developer

Merge Developer Changes

Branches

Default Branch

Feature Branches

GitHub Actions

Example Workflow

Private vs Public

Disconnecting GitHub

Troubleshooting

Best Practices