GitHub Actions & AWS Lambda Orchestrator

A modern web application for orchestrating GitHub Actions and managing AWS Lambda functions. Built with React, TypeScript, Node.js, and Material-UI.

Features

• GitHub Actions Integration: List workflows, view recent runs, and trigger workflows using GitHub App authentication
• AWS Lambda Management: View Lambda functions and invoke them with custom payloads (mocked for local development)
• Modern UI: Material-UI components with responsive design and tabbed interface
• Real-time Updates: Automatic refresh of workflow runs and function status
• Docker Support: Full containerized development environment

Architecture

Frontend (React + TypeScript + Material-UI)
    ↓
Backend API (Node.js + Express + TypeScript)
    ↓
GitHub API (via Octokit) + AWS SDK (future)

Prerequisites

1. Node.js (v18 or higher)
2. Docker & Docker Compose
3. GitHub App (for GitHub Actions integration)

Quick Start

1. Clone and Setup

git clone <your-repo>
cd sf-deploy-app

# Install dependencies
cd backend && npm install
cd ../frontend && npm install

2. GitHub App Configuration

Create a GitHub App

1. Go to GitHub Settings → Developer settings → GitHub Apps

2. Click "New GitHub App"

3. Fill in the following:

   • App name: Your app name
   • Homepage URL: http://localhost:3000 (for development)
   • Webhook URL: Use one of these options:
     • For development: https://example.com/webhook (placeholder - webhooks disabled for now)
     • With ngrok: https://your-ngrok-id.ngrok.io/webhook (see setup below)
     • For production: Your actual domain webhook endpoint
   • Webhook events: Uncheck "Active" for now (we'll enable later)
     • Metadata: Read
   • Where can this GitHub App be installed: Only on this account

4. After creation, note down:

   • App ID
   • Generate and download private key (save as .pem file)

Install the GitHub App

1. Go to your GitHub App settings
2. Click "Install App"
3. Install on your account or organization
4. Select repositories you want to access
5. Note the Installation ID from the URL after installation

Webhook Setup (Optional for Development)

For local development, webhooks are not required since we're polling for workflow status. However, if you want to test webhooks:

Option 1: Use ngrok (Recommended for development)

1. Install ngrok: npm install -g ngrok or download from ngrok.com
2. Start your backend: npm run dev (port 4000)
3. In another terminal: ngrok http 4000
4. Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
5. Update your GitHub App webhook URL to: https://abc123.ngrok.io/webhook
6. Enable "Active" for webhook events

Option 2: Use placeholder URL

• Keep webhook URL as https://example.com/webhook
• Leave webhooks disabled
• The app will work fine without webhooks (polling mode)

3. Environment Configuration

Copy the environment template and configure your GitHub App:

cp backend/.env.example backend/.env

Edit backend/.env with your GitHub App credentials:

# GitHub App Configuration
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...your_private_key_content_here...
-----END RSA PRIVATE KEY-----"
GITHUB_INSTALLATION_ID=12345678

Important Security Notes:

• The .env file is automatically ignored by Git and will not be committed
• Your private key (.pem file) is also protected by .gitignore
• Never commit secrets to version control
• In production, use environment variables or secret management systems

4. Development with Docker

# Start both frontend and backend
docker-compose up --build

# Or start individually
docker-compose up backend
docker-compose up frontend

5. Local Development (Alternative)

# Terminal 1 - Backend
cd backend
npm run dev

# Terminal 2 - Frontend
cd frontend
npm run dev

Usage

1. Access the application: http://localhost:3000
2. GitHub Actions Tab:
   • Select a repository from the dropdown
   • View available workflows
   • Trigger workflows with the "Trigger" button
   • Monitor recent workflow runs
3. Lambda Functions Tab:
   • View Lambda functions (mocked data for now)
   • Invoke functions with custom JSON payloads

Development Workflow

Local Development Commands

# Start development environment
npm run dev                    # Start both frontend and backend with Docker
npm run dev:build             # Rebuild and start containers

# Code quality and formatting
npm run lint                  # Lint both frontend and backend
npm run lint:fix              # Auto-fix linting issues
npm run format                # Format code with Prettier
npm run format:check          # Check if code is properly formatted
npm run type-check            # Run TypeScript type checking
npm run ci                    # Run all checks (CI simulation)

# Building
npm run build                 # Build both frontend and backend
npm run build:frontend        # Build frontend only
npm run build:backend         # Build backend only

# Individual workspace commands
npm run lint:frontend         # Lint frontend only
npm run lint:backend          # Lint backend only

Pre-commit Hooks

The project uses Husky and lint-staged to run quality checks before commits:

• Automatic linting and formatting on staged files
• Type checking and code quality validation
• Prevents commits with linting or formatting errors

CI/CD Pipeline

The project includes GitHub Actions workflows:

Main CI Pipeline (.github/workflows/ci.yml):

• Runs on every push and pull request
• Type checking, linting, and formatting validation
• Build verification for both frontend and backend
• Docker image building (on main branch)

Code Quality Checks (.github/workflows/code-quality.yml):

• Weekly security audits

• Dependency vulnerability scanning

• Code quality reporting

• GET /api/lambda/functions - List Lambda functions

• POST /api/lambda/invoke/:functionName - Invoke a Lambda function

Health Check

• GET /api/health - Application health and service status

Project Structure

sf-deploy-app/
├── backend/
│   ├── src/
│   │   ├── index.ts              # Express server setup
│   │   └── github.service.ts     # GitHub API integration
│   ├── Dockerfile
│   ├── package.json
│   ├── .env.example
│   └── tsconfig.json
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── GitHubActions.tsx # GitHub Actions interface
│   │   │   └── LambdaFunctions.tsx # Lambda functions interface
│   │   ├── App.tsx               # Main application with tabs
│   │   └── main.tsx              # React entry point
│   ├── Dockerfile
│   ├── package.json
│   ├── vite.config.ts
│   └── index.html
├── docker-compose.yml
└── README.md

AWS Lambda Integration (Coming Soon)

The application includes placeholder endpoints for AWS Lambda integration. To enable real Lambda functionality:

1. Install AWS SDK dependencies
2. Configure AWS credentials in .env
3. Replace mocked Lambda endpoints with real AWS SDK calls
4. Add IAM permissions for Lambda invocation

Deployment to AWS

Using AWS Elastic Beanstalk

1. Prepare for deployment:

   # Build the application
   cd backend && npm run build
   cd ../frontend && npm run build

2. Create Beanstalk application:

   • Use the Node.js platform
   • Upload a zip file with the backend build
   • Configure environment variables in Beanstalk console

3. Set up CI/CD pipeline using GitHub Actions:

   • Create .github/workflows/deploy.yml
   • Configure AWS credentials as GitHub secrets
   • Automate build and deploy process

Troubleshooting

GitHub App Issues

• "GitHub service not initialized": Check your environment variables are correctly set
• "403 Forbidden": Ensure your GitHub App has the correct permissions and is installed on the repository
• Private key format: Make sure the private key includes proper line breaks
• Webhook URL required: Use a placeholder URL like https://example.com/webhook during development, or set up ngrok for testing
• Webhook delivery failures: Normal during development - the app works without webhooks using polling mode

Connection Issues

• Backend not accessible: Check if port 4000 is available
• Frontend not loading: Ensure Vite dev server is running on port 3000
• CORS errors: Verify backend CORS configuration includes frontend URL

Docker Issues

• Port conflicts: Stop any processes running on ports 3000 or 4000
• Build failures: Clear Docker cache with docker-compose down && docker system prune

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test locally with Docker
5. Submit a pull request

License

MIT License - see LICENSE file for details