Documentation | DeployBridge - Automated Git Deployment Engine

Overview & Architecture #

DeployBridge eliminates the friction of configuring static web hosting, YAML pipelines, and automated artifact publishing. By analyzing repository metadata, folder structure, and dependency graphs, it dynamically produces tailored GitHub Actions workflows that compile, bundle, and deploy projects to GitHub Pages.

System Architecture Pipeline End-to-End Flow

1

GitHub OAuth Secure token exchange & AES storage

2

Profile Detector Inspection of tree & package.json

3

Workflow Engine Synthesizes Actions YAML files

4

GitHub Pages Automated build & live URL

Zero Infrastructure Overhead

DeployBridge builds directly inside GitHub Actions runners utilizing your repository's native permissions, meaning there are no third-party container hosting fees or external proxy servers required.

5-Minute Quickstart #

Deploy your first static application or website in four simple steps without writing a single line of CI/CD configuration.

Step 1: Sign in with GitHub

Navigate to Sign In and authorize DeployBridge. This requests necessary permissions (read:user, repo, and workflow) to configure repository Actions.

Step 2: Choose Repository

Open the Repositories Browser. DeployBridge automatically indexes all your public and private repositories, showing languages, branches, and commit statistics.

Step 3: Trigger Profile Detection

Click the Deploy to Pages action on any repository. DeployBridge calls /api/v1/github-pages/detect to inspect repository files and determine whether it is plain HTML, React/Vite, Next.js, or Jekyll.

Detected: node-static (Vite build detected via package.json dependencies)

Step 4: Confirm & Launch

Confirm the deployment. DeployBridge commits the optimized workflow template to .github/workflows/deploybridge-<profile>.yml on your default branch and activates GitHub Pages via the GitHub REST API.

OAuth & Authentication #

DeployBridge uses standard GitHub OAuth 2.0 Web Application flow combined with cryptographically signed JSON Web Tokens (JWT) for authenticated API sessions.

OAuth Scope Breakdown

Scope	Usage Purpose	Requirement
read:user	Retrieves basic public profile information and avatar.	Mandatory
user:email	Fetches primary verified email for user account identification.	Mandatory
repo	Enables repository inspection, reading tree, and writing workflows to public & private repos.	Mandatory
workflow	Required by GitHub API to create and update files under `.github/workflows/`.	Mandatory

Supported Deployment Profiles #

DeployBridge supports four specialized deployment profiles to accommodate modern web development stacks:

html Zero Build Step

Static HTML / Vanilla JS

Direct publication of plain HTML5, CSS, and vanilla JavaScript repositories without package managers or compilation.

Output: Root directory (./)

node-static Node 20 + Package Managers

React / Vite / Vue / Astro

Automated dependency install (npm ci, yarn install, or pnpm install) and build execution with multi-dist directory resolution.

Output: dist/, build/, out/

next-static Static Export

Next.js Static Generation

Tailored for Next.js applications configured with output: 'export' in next.config.js or next.config.mjs.

Output: out/ directory

jekyll Ruby Actions

Jekyll Static Sites

Automated Jekyll compilation using Ruby actions and Bundler with _site artifact packaging.

Output: _site/ directory

Auto-Detection Engine #

When deploying in auto mode (the default), the backend performs heuristic analysis across multiple layers of your repository:

1. Root File Tree Inspection

Checks for configuration files such as next.config.js, next.config.mjs, vite.config.js, astro.config.mjs, _config.yml, and Gemfile.

2. Dependency Graph Parsing

Decodes package.json and inspects both dependencies and devDependencies for framework keys (e.g. react, vite, vue, svelte, @angular/core).

3. Server-Side Guardrail

Prevents failed builds by detecting backend server markers (express, fastify, @nestjs/core, hono). If pure backend code is detected, DeployBridge warns the user that the project requires container hosting instead of static pages.

GitHub Actions Generator #

DeployBridge writes standardized, enterprise-grade GitHub Actions workflows using official GitHub Pages actions.

.github/workflows/deploybridge-node-static.yml

name: Deploy to GitHub Pages (DeployBridge)

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

API v1

REST API Reference #

The DeployBridge backend provides a FastAPI REST interface. All endpoints except public login require an HTTP Authorization: Bearer <session_jwt> header.

Base URL: http://localhost:8000/api/v1

GET /auth/login

Generates the official GitHub authorization URL with required OAuth parameters and scopes.

Example Response (200 OK)

{
  "login_url": "https://github.com/login/oauth/authorize?client_id=...&scope=read:user%20user:email%20repo%20workflow"
}

POST /github/repos/info

Fetches in-depth repository telemetry including branch trees, detected tech stack, commits, language breakdown, and Pages status.

Request Body

{
  "owner": "octocat",
  "repository": "my-portfolio"
}

POST /github-pages/detect

Evaluates the repository tree and package dependencies to resolve the best-fitting GitHub Pages deployment profile.

Example Response

{
  "owner": "octocat",
  "repository": "my-portfolio",
  "detected_profile": "node-static",
  "reason": "Vite detected in package.json devDependencies",
  "workflow_template": "node-static.yml",
  "default_branch": "main",
  "selected_branch": "main"
}

POST /github-pages/deploy

Creates or updates the GitHub Pages configuration via the GitHub API, injects the deployment workflow into .github/workflows/, and returns the live preview URL.

Request Payload

{
  "owner": "octocat",
  "repository": "my-portfolio",
  "deployment_profile": "auto"
}

Deploy Response (200 OK)

{
  "message": "GitHub Pages deployment configured successfully",
  "pages_url": "https://octocat.github.io/my-portfolio/",
  "profile": "node-static",
  "workflow_path": ".github/workflows/deploybridge-node-static.yml",
  "status": "active"
}

GET /health

Lightweight liveness probe used for container orchestration and status monitoring.

{ "status": "ok" }

Security & Token Encryption #

Security is built into DeployBridge from the ground up to protect your sensitive GitHub OAuth credentials and repository privileges.

AES-GCM Encrypted Storage

Access tokens are never stored in plaintext. They are encrypted using AES symmetric cryptography with a unique initialization vector (IV) per record before persisting to PostgreSQL.

Stateless JWT Sessions

User client sessions communicate using signed HMAC-SHA256 JWT tokens. Sensitive GitHub tokens never travel across client browser calls after authentication.

Troubleshooting & FAQ #

Solutions to commonly encountered scenarios when deploying repositories.

Why did my GitHub Actions workflow fail with "Resource not accessible by integration"?

In GitHub repository settings under Settings > Actions > General > Workflow permissions, ensure that "Read and write permissions" is selected and "Allow GitHub Actions to create and approve pull requests" is enabled.

How do I configure Next.js for static export?

In your next.config.js or next.config.mjs, specify output: 'export' and disable image optimization if not using a cloud loader:

const nextConfig = {
  output: 'export',
  images: { unoptimized: true }
};
module.exports = nextConfig;

Can I manually override the detected framework?

Yes! In the dashboard deployment confirmation dialog, you can select any profile (html, node-static, next-static, jekyll) from the dropdown selector before submitting the deploy action.

DeployBridge Documentation