NEXUS AI GitHub Integration: The Complete Guide to Auto-Deploying from Your Repository

Connecting your GitHub repository to NEXUS AI unlocks a fully automated deployment pipeline — push code, and your app is live within minutes on GCP Cloud Run, AWS ECS Fargate, Azure Container Apps, or NEXUS AI Container. This guide walks through every step: installing the GitHub App, binding a repo, configuring auto-deploy rules, and understanding the webhook system that powers it all.

---

Why Integrate GitHub with NEXUS AI?

Modern software teams live in GitHub. Your pull requests, code reviews, branch strategies, and release tags all live there — so your deployment pipeline should follow that same source of truth.

The NEXUS AI GitHub integration makes your repository the single trigger for deployments:

• No manual image builds or docker push commands
• No CI pipeline boilerplate to maintain
• Branch-level control over which pushes trigger a deploy
• Encrypted environment variables stored securely at the binding level
• Full webhook audit trail — see every event NEXUS AI received from GitHub

---

Step 1: Install the NEXUS AI GitHub App

To connect GitHub to NEXUS AI, you need to install the NEXUS AI GitHub App on your GitHub account or organisation.

1. Log in to your NEXUS AI dashboard at nexusai.run.
2. Navigate to Integrations → GitHub (or open any project and click Connect GitHub).
3. Click the Connect GitHub button. You will be redirected to GitHub's App installation page.
4. Choose whether to install on your personal account or a GitHub organisation.
5. Select the repositories you want to grant access to (you can choose All repositories or restrict to specific ones).
6. Confirm the installation. GitHub will redirect you back to NEXUS AI with your installation ID automatically captured.

Required GitHub App Permissions

The NEXUS AI GitHub App requests the minimum permissions needed to operate:

Permission	Level	Purpose
Repository contents	Read	Clone source code to build containers
Webhook events	Push	Receive push notifications to trigger deployments

No write access to your repository is ever requested. NEXUS AI only reads code and listens for push events.

---

Step 2: Bind a Repository to a Deployment Target

Once the app is installed, you need to bind a GitHub repo to a deployment target in NEXUS AI. A binding links one branch (or set of branches) to one runtime environment with its own build configuration.

Creating a Repo Binding

In the NEXUS AI dashboard:

1. Go to Deployments → New Deployment or open an existing project.
2. Select GitHub as the source.
3. Choose your installed GitHub account/org and pick a repository from the dropdown.
4. Configure the binding options below.

Repo Binding Configuration Options

Each binding exposes the following fields:

Branch control

• allowedBranches — JSON array of branch names allowed to trigger deployments. Example: ["main", "production"]. Pushes to any other branch are silently ignored.

Deployment behaviour

• autoDeploy — Boolean. When true, every push to an allowed branch queues a deployment automatically. When false, you must trigger deploys manually.
• projectId — Associate this binding with a NEXUS AI project for grouping and access control.

Build configuration

• buildMode — Build strategy. NEXUS AI auto-detects the language and framework, or you can override it.
• installCommand — Dependency installation step. Example: npm ci
• buildCommand — Build step. Example: npm run build
• startCommand — Container entrypoint. Example: node server.js
• outputDir — Build output directory (used for static sites and SSR frameworks).
• servicePort — The port your application listens on inside the container. Example: 3000

Runtime target

• runtimeTarget — Where to deploy the container. Options:
  • gcp_cloud_run — Google Cloud Run (serverless containers)
  • aws_ecs_fargate — AWS ECS with Fargate (serverless containers)
  • azure_container_apps — Azure Container Apps
  • Container — NEXUS AI

Serving

• subdomain — NEXUS AI-managed subdomain (e.g. myapp.nexusai.run)
• customDomain — Your own domain (e.g. app.example.com)
• envVars — Environment variables stored encrypted at rest. Never visible in logs or UI after saving.

Example: Node.js App to GCP Cloud Run

{
  "allowedBranches": ["main", "production"],
  "autoDeploy": true,
  "runtimeTarget": "gcp_cloud_run",
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "startCommand": "node server.js",
  "servicePort": 3000,
  "subdomain": "myapp",
  "envVars": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgresql://..."
  }
}

---

Step 3: Enable Auto-Deploy from GitHub

Auto-deploying from GitHub is controlled by two settings working together: autoDeploy and allowedBranches.

With autoDeploy: true and allowedBranches: ["main"], the full deployment flow is:

1. You run git push origin main
2. GitHub sends a push event webhook to https://nexusai.run/api/github/webhook
3. NEXUS AI verifies the HMAC-SHA256 signature on the x-hub-signature-256 header to confirm the event is genuine
4. NEXUS AI checks if the pushed branch (main) is in your allowedBranches list
5. NEXUS AI checks that autoDeploy is enabled on the binding
6. A deployment job is queued and picked up by a worker (up to 5 concurrent builds per worker, polling every 2 seconds)
7. Your container is built from source and pushed to the target runtime
8. Status progresses through: queued → building → deploying → success (or failed)

Duplicate Commit Protection

NEXUS AI deduplicates deployments by commit SHA. If you push the same commit twice (e.g. via a force-push that does not change the tree), NEXUS AI will not re-deploy it. Additionally, if a newer commit arrives while an older one is still queued, the older job is superseded — you always deploy the latest code, never a stale intermediate commit.

---

Step 4: Manual Deployments

You do not have to rely on push webhooks. To trigger a deployment on demand:

Via the dashboard: Open the binding and click the Deploy button. NEXUS AI fetches the latest commit on the configured branch and queues a build.

Via the REST API:

curl -X POST https://nexusai.run/api/github/bindings/:bindingId/deploy \
  -H "Authorization: Bearer <your-api-token>"

Replace :bindingId with the UUID of your repo binding, visible in the binding detail page URL.

---

Step 5: Understanding the Webhook System

Every push event GitHub sends to NEXUS AI is recorded in the Webhook Deliveries tab of your binding. This gives you a full audit trail of what happened and why.

What You Can See

Field	Description
Delivery ID	GitHub's unique ID for the webhook delivery
Event type	Always push for deployment triggers
Status	ok, ignored, or failed
Reason	Why the event was ignored (if applicable)
Timestamp	When the event was received

Common "Ignored" Reasons

Reason	Meaning
autoDeploy disabled	The binding has autoDeploy: false
branch not in allowedBranches	The pushed branch is not in your allowed list
installation suspended	The GitHub App install was suspended by a GitHub admin
duplicate commit	This exact commit SHA was already deployed

The webhook endpoint is: https://nexusai.run/api/github/webhook

All payloads are verified using HMAC-SHA256 with a per-installation secret. Requests with an invalid or missing x-hub-signature-256 header are rejected immediately with no processing.

---

GitHub Actions Integration

NEXUS AI does not replace GitHub Actions — it complements it. A common pattern is to run your test suite in GitHub Actions and only deploy when tests pass, using the NEXUS AI manual deploy API as the final step:

# .github/workflows/deploy.yml
name: Test and Deploy

on:
  push:
    branches: [main]

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 test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Trigger NEXUS AI deployment
        run: |
          curl -X POST \
            "https://nexusai.run/api/github/bindings/$NEXUS_BINDING_ID/deploy" \
            -H "Authorization: Bearer $NEXUS_API_TOKEN" \
            -H "Content-Type: application/json"
        env:
          NEXUS_BINDING_ID: ${{ secrets.NEXUS_BINDING_ID }}
          NEXUS_API_TOKEN: ${{ secrets.NEXUS_API_TOKEN }}

Add NEXUS_BINDING_ID and NEXUS_API_TOKEN as GitHub Actions secrets in your repository settings (Settings → Secrets and variables → Actions). With this pattern, set autoDeploy: false on the NEXUS AI binding — deployments are controlled entirely by your Actions workflow, not raw push events.

---

Frequently Asked Questions

Q: Which GitHub plan do I need?
A: The NEXUS AI GitHub App works with free, Pro, Team, and Enterprise GitHub plans. It supports both personal accounts and organisations.

Q: Can I bind the same repo to multiple deployment targets?
A: Yes. You can create multiple bindings for the same repository — for example, one binding deploying main to production on GCP Cloud Run and another deploying staging to a Docker host.

Q: How do I rotate my webhook secret?
A: Reinstall or refresh the GitHub App connection from the NEXUS AI integrations page. A new installation ID and secret are generated automatically.

Q: Are environment variables secure?
A: Yes. All values stored in envVars on a binding are encrypted at rest using AES-256-GCM. They are injected into the container at runtime and never logged or exposed in the dashboard after the initial save.

Q: What happens if a deployment fails?
A: The deployment status is set to failed. Your previous deployment continues running — NEXUS AI uses a rolling deployment strategy and never takes down a live container until a healthy replacement is confirmed. Build logs are available in the Deployments tab and you can trigger a retry at any time.

Q: How do I disconnect GitHub?
A: You can suspend or uninstall the NEXUS AI GitHub App at any time from GitHub → Settings → Applications → Installed GitHub Apps. In-flight deployments will complete; all future webhooks will be rejected.

Q: Can I use GitHub integration with a monorepo?
A: Yes. Use the buildCommand and outputDir fields to scope the build to a specific package or subdirectory. For example: "buildCommand": "cd packages/api && npm run build".

---

Summary

The NEXUS AI GitHub integration connects your repository to a fully automated, cloud-native deployment pipeline in three steps: install the GitHub App, create a repo binding with your target runtime and build configuration, then enable autoDeploy. Every push to an allowed branch is cryptographically verified, deduplicated by commit SHA, and deployed — with a full webhook audit trail so you always know exactly what happened and why.

For questions or support, visit the NEXUS AI documentation or open a support ticket from your dashboard.