The Git Integration System: How Deployxa Connects to GitHub
Deployxa connects to GitHub to automatically deploy your app when you push to the main branch. This Git integration is what makes the "push to deploy" experience possible: you push code, and the platform handles the rest. But building a secure, reliable Git integration requires careful engineering: handling webhooks, cloning repositories, managing branch deployments, and securing GitHub credentials. Here is how the system works.
The direct answer is that Deployxa's Git integration has four components: the GitHub App (which provides secure access to your repositories), the webhook handler (which receives push events from GitHub), the repository cloner (which clones the repository for building), and the branch deployment manager (which maps branches to deployments). The system is secure (uses GitHub App tokens, not personal access tokens), reliable (handles webhook retries), and flexible (supports branch-based deployments). For more on the deployment process, see our article on how we built the CI/CD pipeline.
The Four Components
1. The GitHub App
Deployxa uses a GitHub App (not a personal access token) to access your repositories. A GitHub App provides scoped access (only the repositories you authorize), per-user installation (each user connects their own GitHub account), and webhook delivery (GitHub sends push events to Deployxa). This is more secure than personal access tokens, which provide broad access to all repositories.
2. The webhook handler
When you push to GitHub, GitHub sends a webhook event (push event) to Deployxa's webhook handler. The handler verifies the webhook's signature (to ensure it is from GitHub), parses the event (to determine which repository and branch was pushed), and triggers the deployment pipeline.
3. The repository cloner
The deployment pipeline clones the repository (via a shallow clone, which is fast and uses minimal disk space). The clone is used for the build stage (which compiles the code and produces the Docker image).
4. The branch deployment manager
The branch deployment manager maps branches to deployments. By default, the main branch deploys to production. You can configure other branches to deploy to staging or preview environments. The manager handles branch-specific configuration (e.g., different environment variables for staging vs. production).
Step-by-Step: How a Push Triggers a Deployment
Step 1: You push to GitHub
You push code to the main branch: git push origin main.
Step 2: GitHub sends a webhook
GitHub sends a push event webhook to Deployxa's webhook handler.
Step 3: Deployxa verifies the webhook
The webhook handler verifies the webhook's signature (using the GitHub App's secret), to ensure it is from GitHub and not from an attacker.
Step 4: Deployxa triggers the pipeline
The handler parses the event, determines which repository and branch was pushed, and triggers the deployment pipeline.
Step 5: The pipeline clones the repository
The pipeline clones the repository (shallow clone, depth 1), which is fast (typically 5-10 seconds).
Step 6: The pipeline builds and deploys
The pipeline runs the build, starts the new container, runs the readiness check, and swaps traffic. For more on the pipeline, see our article on how we built the CI/CD pipeline.
Common Pitfalls and Troubleshooting
The first pitfall is webhook delivery failures. GitHub retries webhooks if they fail, but if the webhook handler is down for an extended period, push events are lost. The fix is to make the webhook handler highly available and to have a fallback (e.g., a manual trigger via the dashboard). The second pitfall is webhook signature verification. If the GitHub App's secret is rotated, the webhook handler might reject valid webhooks. The fix is to update the secret on both sides (GitHub and Deployxa) simultaneously. The third pitfall is large repositories. Cloning a large repository (e.g., 1GB+) is slow, which delays deployments. The fix is to use a shallow clone (depth 1), which only clones the latest commit, and to use .gitignore to exclude large files. The fourth pitfall is branch misconfiguration. If branches are misconfigured (e.g., the staging branch deploys to production), the wrong version might be deployed. The fix is to clearly document the branch-to-environment mapping and to verify it before deploying. The fifth pitfall is token expiration. GitHub App tokens expire (typically after 1 hour), which means the platform needs to refresh them. The fix is to implement token refresh logic and to handle expired tokens gracefully.
Advanced Git Integration Patterns
Beyond the basics, Deployxa's Git integration supports several advanced patterns. The first is monorepo support. For monorepos (repositories with multiple services), the Git integration can detect multiple services in a single repository and deploy each one independently. The ingestion service scans the repository for manifest files (e.g., package.json, requirements.txt) in different directories, and each directory is treated as a separate service. This means a single Git push can trigger multiple deployments (one per service). For more on monorepo deployment, see our article on deploying a FastAPI + Next.js monorepo.
The second pattern is branch-based environments. The Git integration can map branches to environments (e.g., main -> production, staging -> staging, feature/* -> preview). Each environment has its own configuration (environment variables, custom domains, resource profile), which means you can test changes in staging before promoting to production. Preview environments (for pull requests) are created automatically and destroyed when the pull request is merged or closed.
The third pattern is deployment previews. For pull requests, the Git integration can create a preview deployment (a temporary deployment with a unique URL) that lets reviewers test the changes before merging. Preview deployments are created automatically when a pull request is opened, updated when the pull request is updated, and destroyed when the pull request is merged or closed. This is similar to Vercel's preview deployments, but on Deployxa's persistent containers.
The fourth pattern is deployment retries. If a deployment fails (e.g., due to a build error), the Git integration can automatically retry (with the AutoRepairService fixing common issues like missing dependencies). If the retry also fails, the integration notifies the team (via Slack or the dashboard) with the error details and a link to the build log. For more on the AutoRepairService, see our article on the autonomous build self-healing engine.
The fifth pattern is deployment policies. The Git integration can enforce deployment policies (e.g., "only deploy from the main branch", "require approval for production deployments", "block deployments during business hours"). Policies are configured via the dashboard and enforced by the integration, which prevents accidental or unauthorized deployments.
How the Git Integration Integrates with the MCP Server
The Git integration is exposed via the Deployxa MCP server, which means your AI assistant (in Cursor or Claude Desktop) can trigger and monitor deployments directly. For example, you can say "deploy the current branch to staging," and your AI assistant calls deployxa_deploy_workflow with the current branch, waits for the build, calls deployxa_get_readiness, and reports the result. If the deployment fails, the assistant can call deployxa_get_build_log to diagnose the issue and propose a fix. This is the agentic deployment workflow, where the AI assistant handles the entire deployment process. For more on the MCP server, see our article on giving Cursor cloud superpowers.
Lessons Learned
Building the Git integration taught us several lessons. First, the GitHub App is more secure than personal access tokens. The GitHub App provides scoped access (only the repositories you authorize) and per-user installation (each user connects their own GitHub account), which is more secure than personal access tokens (which provide broad access to all repositories). Second, webhook reliability is critical. GitHub retries webhooks if they fail, but if the webhook handler is down for an extended period, push events are lost. The fix is to make the webhook handler highly available and to have a fallback (e.g., a manual trigger via the dashboard). Third, shallow clones are essential for speed. Cloning a large repository (1GB+) is slow, which delays deployments. Shallow clones (depth 1) only clone the latest commit, which is fast (5-10 seconds) and sufficient for building. Fourth, branch-based environments are a game-changer for team workflows. Being able to deploy different branches to different environments (staging, preview) enables parallel development and testing, which speeds up the development cycle. Fifth, the Git integration needs to be transparent. Developers need to see what happened (which commit was deployed, when, and with what result), which means the integration needs to log everything and display it in the dashboard. For more on Deployxa's engineering, see our articles on how we built the CI/CD pipeline and build log streaming.
Conclusion: A Secure, Reliable Git Integration
Deployxa's Git integration connects to GitHub via a GitHub App (secure, scoped access), handles webhooks (reliable, verified), clones repositories (fast, shallow), and manages branch deployments (flexible, configurable). By understanding how the integration works, you can troubleshoot deployment issues and configure branch-based deployments. For more on Deployxa's engineering, see our articles on how we handle DDoS protection and the container image registry. Learn about the build log streaming system and how we built the CI/CD pipeline in our companion articles. Explore our free developer tools. Try Deployxa Drop for an instant live preview.