GitHub App Setup

Reoclo uses a GitHub App to integrate with your repositories. The app receives push webhooks to trigger auto-deploy, generates short-lived tokens to clone private repos during deployment, and updates deployment statuses on GitHub.

What the GitHub App Does

When you install the Reoclo GitHub App on your GitHub account or organization, it enables three capabilities:

• Push webhooks: Reoclo receives notifications when you push to a branch, enabling auto-deploy
• Repository cloning: During deployment, Reoclo generates a short-lived token to clone your repo directly onto the target server. No long-lived credentials are stored.
• Deployment status: Reoclo creates GitHub Deployments and updates their status (pending, in progress, success, failure), visible in your GitHub repo

Installing the GitHub App

1. In the Reoclo dashboard, navigate to Settings → Integrations
2. Click Install GitHub App
3. You’ll be redirected to GitHub
4. Choose your account or organization
5. Select which repositories to grant access to:
   • All repositories: Reoclo can access all current and future repos
   • Only select repositories: Choose specific repos (recommended)
6. Click Install & Authorize

You’ll be redirected back to the Reoclo dashboard. The selected repositories will now appear when creating applications.

Tip

Start with specific repositories rather than granting access to all. You can always add more repos later without reinstalling the app.

Permissions Requested

The GitHub App requests minimal permissions:

Permission	Access	Purpose
Contents	Read	Clone repositories onto target servers during deployment
Deployments	Read & Write	Create GitHub Deployment records and update their status
Metadata	Read	Required by GitHub for all apps (read repo names, visibility)
Pull requests	Read	Read PR data for preview deployments

The app also subscribes to these webhook events:

• Push: Triggers auto-deploy when you push to a configured branch
• Pull request: Triggers preview deployments on PR open, sync, and close
• Installation: Notifies Reoclo when the app is installed or uninstalled
• Repository: Syncs metadata when repos are renamed, archived, or deleted

Note

Reoclo never stores long-lived GitHub credentials. Installation tokens are generated on-demand, used once for cloning during a deployment, and discarded. They expire shortly after use.

Managing Repository Access

After installation, you can change which repositories Reoclo has access to:

1. Go to GitHub Settings → Integrations → Applications (or GitHub Settings → Applications → Installed GitHub Apps)
2. Find Reoclo in the list
3. Click Configure
4. Under Repository access, add or remove repositories
5. Click Save

Changes take effect immediately. If you remove a repository that has an application configured in Reoclo, deployments for that application will fail until access is restored.

How Cloning Works

When a deployment runs, Reoclo:

1. Generates a short-lived token for the specific repository
2. Uses the token to shallow-clone the repo directly onto your target server
3. The token is passed securely and never written to disk or logged
4. After cloning, the token is discarded

Your source code goes directly from GitHub to your server. It never passes through or is stored on Reoclo’s infrastructure.

Auto-Deploy on Push

Once the GitHub App is installed, you can enable auto-deploy per application:

1. In the Reoclo dashboard, go to your application’s settings
2. Enable Auto-Deploy
3. Select the branch to watch (e.g., main or production)

Now, every push to that branch triggers an automatic deployment. The flow:

1. You push code to the configured branch
2. GitHub sends a push webhook to Reoclo
3. Reoclo verifies the webhook signature
4. A deployment is queued and executed on your target server

Caution

Auto-deploy triggers on every push to the configured branch. For production applications, consider keeping auto-deploy disabled and deploying manually after testing.

Uninstalling the GitHub App

To remove Reoclo’s access to your repositories:

1. Go to GitHub Settings → Integrations → Applications (or GitHub Settings → Applications → Installed GitHub Apps)
2. Find Reoclo in the list
3. Click Configure
4. Scroll to the bottom and click Uninstall

This immediately revokes Reoclo’s access. Existing applications in Reoclo that reference those repositories will fail to deploy until access is restored.

Troubleshooting

Repositories Don’t Appear When Creating an Application

Cause: The GitHub App doesn’t have access to those repositories.

Fix: Go to GitHub Settings → Applications → Reoclo → Configure, and add the missing repositories.

Auto-Deploy Isn’t Triggering

Cause: Auto-deploy may be disabled, or the webhook isn’t reaching Reoclo.

Fix:

1. Verify auto-deploy is enabled in your application settings
2. Check the branch configuration matches the branch you’re pushing to
3. In GitHub, go to your repo’s Settings → Webhooks and check the delivery history for errors

Deployment Fails with “Token Generation Failed”

Cause: The GitHub App installation may be suspended or the repository was removed from the app’s access.

Fix: Go to GitHub Settings → Applications → Reoclo → Configure, and verify the repository is included and the installation is active.

Deployment Fails with “Clone Failed”

Cause: The repository may be private and the app doesn’t have Contents:Read permission, or the repo was deleted/archived.

Fix: Verify the repository exists, is not archived, and is included in the GitHub App’s repository access list.

Next Steps

• Quickstart: Deploy your first application
• Deployments Overview: Understand the full deployment pipeline
• Deployment Configuration: Configure auto-deploy, health checks, and environment variables