OpenNoodl/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-005-deployment-automation/DEPLOY-001-README.md

DEPLOY-001: Deployment Automation via GitHub Actions

Overview

Enable one-click deployments from Nodegex to multiple hosting targets (Vercel, Netlify, Cloudflare Pages, etc.) by leveraging GitHub Actions as the CI/CD orchestration layer. This builds directly on GIT-004's OAuth foundation and GitHubClient.

Phase: 3 (Dashboard UX & Collaboration)
Priority: HIGH (completes the development lifecycle)
Total Effort: 44-60 hours across 6 sub-tasks
Risk: Medium (workflow complexity, multi-target support)

Hard Dependency: GIT-004A (OAuth & GitHubClient with Actions API)

---

Strategic Value

Complete Development Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│                    Nodegex Development Lifecycle                │
│                                                                 │
│   ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐    │
│   │Build │ ─► │ Git  │ ─► │ PR   │ ─► │Review│ ─► │Deploy│    │
│   │      │    │Commit│    │Create│    │Merge │    │      │    │
│   └──────┘    └──────┘    └──────┘    └──────┘    └──────┘    │
│       │                                               │        │
│       └───────────────────────────────────────────────┘        │
│                    All within Nodegex                          │
└─────────────────────────────────────────────────────────────────┘

Why GitHub Actions?

Approach	Build Time	Cost	Maintenance
Custom CI/CD	Months	$	High
GitHub Actions	Days	Free*	GitHub's problem

*Free for public repos, included in GitHub plans for private

---

Feature Set

Core Features

Feature	Description	Sub-Task
Deploy Button	One-click deploy from editor toolbar	DEPLOY-001C
Workflow Generator	Auto-create GitHub Actions workflows	DEPLOY-001B
Deploy Status	Real-time build progress in editor	DEPLOY-001C
Multi-Target	Vercel, Netlify, Cloudflare, AWS, etc.	DEPLOY-001D
PR Previews	Auto-deploy preview for every PR	DEPLOY-001F
Environments	Manage prod, staging, dev configs	DEPLOY-001E

Integration with GIT-004

GIT-004 Feature	DEPLOY-001 Enhancement
PR Panel	+ Preview URL display
Dashboard Widgets	+ Deployment status
Component Linking	+ Deploy history per component
Issues	+ Auto-create on deploy failure

---

Architecture

Build on GitHubClient

// GIT-004A creates the foundation
class GitHubClient {
  readonly issues: IssuesAPI;      // GIT-004B-D
  readonly pullRequests: PRsAPI;   // GIT-004C
  readonly actions: ActionsAPI;    // DEPLOY-001 uses this
  readonly repos: ReposAPI;        // For workflow file management
}

// DEPLOY-001 adds deployment-specific services
class DeploymentService {
  constructor(private github: GitHubClient) {}
  
  async triggerDeploy(environment: string): Promise<WorkflowRun> {
    return this.github.actions.triggerWorkflow(
      owner, repo, 'deploy.yml', 'main',
      { environment }
    );
  }
  
  async getDeploymentStatus(): Promise<DeploymentStatus> {
    const runs = await this.github.actions.listWorkflowRuns(owner, repo, {
      workflow_id: 'deploy.yml'
    });
    return this.parseDeploymentStatus(runs);
  }
}

Workflow Generation

// Template-based workflow generation
interface WorkflowTemplate {
  target: 'vercel' | 'netlify' | 'cloudflare' | 'aws' | 'github-pages';
  buildCommand: string;
  outputDir: string;
  nodeVersion: string;
  environments: string[];
}

class WorkflowGenerator {
  generate(template: WorkflowTemplate): string {
    return `
name: Deploy to ${template.target}
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'preview'
        type: choice
        options: [${template.environments.join(', ')}]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '${template.nodeVersion}'
      - run: npm ci
      - run: ${template.buildCommand}
      ${this.getTargetSteps(template)}
`;
  }
}

---

Sub-Task Breakdown

DEPLOY-001A: Actions API Integration (6-8 hours)

Depends on: GIT-004A
Branch: task/deploy-001a-actions-api

Extend GitHubClient with full Actions API support and create React hooks for deployment state.

Scope:

• Add Actions API methods to GitHubClient
• Create useWorkflows hook
• Create useWorkflowRuns hook with polling
• Create useDeploymentStatus hook
• Add "Deployments" tab to GitHub Panel

Files to Create:

packages/noodl-editor/src/editor/src/services/github/
├── ActionsAPI.ts              # Actions API wrapper
└── DeploymentService.ts       # High-level deployment operations

packages/noodl-editor/src/editor/src/views/panels/GitHubPanel/
├── components/
│   └── DeploymentsTab/
│       ├── DeploymentsList.tsx
│       ├── DeploymentItem.tsx
│       ├── DeploymentDetail.tsx
│       └── WorkflowRunStatus.tsx
├── hooks/
│   ├── useWorkflows.ts
│   ├── useWorkflowRuns.ts
│   └── useDeploymentStatus.ts

Success Criteria:

• Can list workflows for connected repo
• Can view workflow run history
• Real-time status polling works
• Deployments tab shows in GitHub Panel

---

DEPLOY-001B: Workflow Generator (10-14 hours)

Depends on: DEPLOY-001A
Branch: task/deploy-001b-workflow-generator

Create system to generate and commit GitHub Actions workflow files.

Scope:

• Workflow template engine
• Project analysis for build configuration detection
• Target-specific generators (start with Vercel)
• Commit workflow file to repository
• Setup wizard UI

Files to Create:

packages/noodl-editor/src/editor/src/services/deployment/
├── WorkflowGenerator.ts
├── WorkflowTemplates.ts
├── ProjectAnalyzer.ts          # Detect build config
└── types.ts

packages/noodl-editor/src/editor/src/views/deployment/
├── SetupWizard/
│   ├── SetupWizard.tsx
│   ├── TargetSelector.tsx
│   ├── ConfigurationStep.tsx
│   ├── ReviewStep.tsx
│   └── SetupWizard.module.scss

Success Criteria:

• Can detect project build configuration
• Can generate valid workflow YAML
• Setup wizard guides user through configuration
• Workflow committed to repo successfully
• Generated workflow runs successfully on GitHub

---

DEPLOY-001C: Deploy Button & Status UI (8-12 hours)

Depends on: DEPLOY-001A
Branch: task/deploy-001c-deploy-button

Add one-click deploy button to editor and real-time deployment status.

Scope:

• Deploy button in editor toolbar
• Environment selector dropdown
• Deployment progress popover
• Success/failure notifications
• Link to live URL on success
• Link to logs on failure

Files to Create:

packages/noodl-editor/src/editor/src/views/deployment/
├── DeployButton/
│   ├── DeployButton.tsx
│   ├── DeployButton.module.scss
│   ├── EnvironmentDropdown.tsx
│   └── DeployProgressPopover.tsx
├── DeployNotification.tsx
└── hooks/
    └── useDeployAction.ts

Files to Modify:

packages/noodl-editor/src/editor/src/views/EditorTopbar/
  - Add DeployButton component

Success Criteria:

• Deploy button visible in toolbar
• Can select environment (prod/staging/preview)
• Shows real-time progress during deployment
• Success notification with live URL
• Failure notification with link to logs
• Button disabled during active deployment

---

DEPLOY-001D: Multi-Target Templates (8-10 hours)

Depends on: DEPLOY-001B
Branch: task/deploy-001d-multi-target

Create workflow templates for all major hosting targets.

Scope:

• Vercel template (with preview deploys)
• Netlify template
• Cloudflare Pages template
• AWS Amplify template
• GitHub Pages template
• Custom/self-hosted template

Files to Create:

packages/noodl-editor/src/editor/src/services/deployment/
├── templates/
│   ├── vercel.ts
│   ├── netlify.ts
│   ├── cloudflare.ts
│   ├── aws-amplify.ts
│   ├── github-pages.ts
│   └── custom.ts
├── TargetDetector.ts           # Suggest target based on existing config
└── SecretsGuide.ts             # Per-target secrets documentation

Success Criteria:

• Each template generates valid, working workflow
• Templates include preview deploy support where applicable
• Secrets requirements documented per target
• Target auto-detection works (vercel.json → Vercel)

---

DEPLOY-001E: Environment Management (6-8 hours)

Depends on: DEPLOY-001C
Branch: task/deploy-001e-environments

Manage deployment environments (production, staging, development).

Scope:

• Environment configuration UI
• Environment-specific variables
• Deploy protection rules guidance
• Environment status dashboard

Files to Create:

packages/noodl-editor/src/editor/src/views/deployment/
├── EnvironmentManager/
│   ├── EnvironmentManager.tsx
│   ├── EnvironmentCard.tsx
│   ├── EnvironmentConfig.tsx
│   └── EnvironmentManager.module.scss
├── SecretsSetupGuide.tsx

Success Criteria:

• Can configure multiple environments
• Environment-specific deploy buttons work
• Clear guidance on secrets setup
• Environment status visible in dashboard

---

DEPLOY-001F: PR Preview Integration (6-8 hours)

Depends on: DEPLOY-001D, GIT-004C
Branch: task/deploy-001f-pr-previews

Integrate preview deployments with the PR panel.

Scope:

• Auto-deploy on PR creation/update
• Extract preview URL from workflow
• Display preview URL in PR detail
• Preview cleanup on PR close
• Comment on PR with preview link (optional)

Files to Modify:

packages/noodl-editor/src/editor/src/views/panels/GitHubPanel/
  components/PullRequestsTab/PRDetail.tsx
  - Add preview URL section
  - Add "Open Preview" button

packages/noodl-editor/src/editor/src/services/deployment/
  templates/*.ts
  - Ensure all templates support preview deploys

Success Criteria:

• PRs show preview URL when available
• Preview URL extracted from workflow run
• "Open Preview" button works
• Preview status shows (building/ready/failed)

---

Implementation Order

Week 1:
└── DEPLOY-001A: Actions API Integration (6-8 hrs)

Week 2:
├── DEPLOY-001B: Workflow Generator (10-14 hrs)
└── DEPLOY-001C: Deploy Button (start)

Week 3:
├── DEPLOY-001C: Deploy Button (complete) (8-12 hrs)
└── DEPLOY-001D: Multi-Target Templates (8-10 hrs)

Week 4:
├── DEPLOY-001E: Environment Management (6-8 hrs)
└── DEPLOY-001F: PR Previews (6-8 hrs)

Week 5:
└── Integration testing & polish

---

Testing Checklist

Workflow Generation

• Vercel workflow builds and deploys successfully
• Netlify workflow builds and deploys successfully
• Preview deploys create unique URLs
• Environment variables passed correctly

Deploy Button

• Triggers correct workflow
• Shows accurate progress
• Handles concurrent deploy attempts
• Error states display correctly

PR Previews

• Preview URL appears in PR panel
• URL is correct and accessible
• Preview updates on new commits
• Status shows building/ready/failed

Dashboard Integration

• Deployment status shows on project cards
• Recent deploys in activity feed
• Click-through to deployment details works

---

OAuth Permissions

Ensure GIT-004A requests the workflow scope:

const OAUTH_SCOPES = [
  'repo',       // Code, issues, PRs
  'read:user',  // User profile
  'workflow',   // Trigger and manage workflows ← Required for DEPLOY-001
];

---

Files Summary

Create (New)

packages/noodl-editor/src/editor/src/services/
├── github/
│   ├── ActionsAPI.ts
│   └── DeploymentService.ts
└── deployment/
    ├── WorkflowGenerator.ts
    ├── WorkflowTemplates.ts
    ├── ProjectAnalyzer.ts
    ├── TargetDetector.ts
    ├── templates/
    │   ├── vercel.ts
    │   ├── netlify.ts
    │   ├── cloudflare.ts
    │   ├── aws-amplify.ts
    │   ├── github-pages.ts
    │   └── custom.ts
    └── types.ts

packages/noodl-editor/src/editor/src/views/
├── deployment/
│   ├── SetupWizard/
│   ├── DeployButton/
│   ├── EnvironmentManager/
│   └── SecretsSetupGuide.tsx
└── panels/GitHubPanel/components/
    └── DeploymentsTab/

Modify

packages/noodl-editor/src/editor/src/services/github/GitHubClient.ts
  - Add actions API support (may already be in GIT-004A)

packages/noodl-editor/src/editor/src/views/EditorTopbar/
  - Add DeployButton

packages/noodl-editor/src/editor/src/views/panels/GitHubPanel/
  - Add DeploymentsTab
  - Enhance PRDetail with preview URL

packages/noodl-editor/src/editor/src/views/Dashboard/
  - Add deployment status to project cards

---

Dependencies

NPM Packages

{
  "js-yaml": "^4.1.0"  // For workflow YAML generation
}

(Most dependencies already covered by GIT-004)

Blocked By

• GIT-004A: OAuth & GitHubClient (hard dependency)
• GIT-004C: PR Panel (for PR preview integration)
• GIT-004F: Dashboard Widgets (for deployment status display)

Blocks

• Future: Rollback UI
• Future: Deploy scheduling
• Future: A/B deployments

---

Success Metrics

Metric	Target	Measurement
Setup completion	70%	Users who complete wizard
Deploy frequency	5/week	Average deploys per active project
Deploy success rate	95%	Successful / total deploys
Time to first deploy	< 10 min	From wizard start to live
PR preview adoption	60%	PRs with previews viewed

---

References

• GitHub Actions Documentation
• Vercel GitHub Actions
• Netlify CLI Deploy
• DEPLOY-000: Synergy Overview
• GIT-004: GitHub Integration