Release Coordinator

A modern, collaborative release management platform designed to streamline software deployment coordination across teams and services. Built for engineering teams who need visibility, control, and coordination across complex multi-service releases.

📋 Overview

Release Coordinator helps teams plan, track, and deploy software releases with confidence. Whether you're managing microservices, coordinating sprint deployments, or orchestrating complex multi-service releases, this platform provides the visibility and coordination tools your team needs.

✨ Features

Core Capabilities

Multi-Service Release Management - Track and coordinate releases across multiple services and repositories
Sprint Planning & Tracking - Organize releases by sprint with comprehensive status tracking
Deployment Groups - Group related releases and control deployment order (parallel or sequential)
Release Dependencies - Define and track dependencies between releases to prevent deployment issues
Kanban Board - Visual release management with drag-and-drop status updates
Team Collaboration - Comments, activity feeds, and real-time updates for team coordination

Integrations

Clerk Authentication - Secure, multi-tenant authentication with organization support
Jira Integration - Link releases to Jira tickets and sync project information
GitHub Integration - Connect repositories and track deployment status
Slack Notifications - Automated alerts for status changes, blockers, and deployment readiness
OAuth Support - Secure token management with automatic refresh

Advanced Features

Role-Based Access Control - Team admin, member, and viewer roles
Release Items & Dependencies - Granular tracking of PRs, tickets, and blockers
Status Workflows - Comprehensive release lifecycle (Planning → Development → Testing → Ready → Deployed)
Hotfix Management - Fast-track critical fixes with priority flagging
Activity Tracking - Complete audit trail of all release changes
Team Invitations - Email-based team member invitations with role assignment

🛠 Tech Stack

Frontend & Framework

Next.js - React framework with App Router
React - UI library
TypeScript - Type-safe development
Tailwind CSS - Utility-first CSS framework
Radix UI - Accessible component primitives
Lucide React - Icon library

Backend & Database

Prisma - Next-generation ORM
PostgreSQL - Primary database (via Neon)
Next.js API Routes - RESTful API endpoints

State Management & Data Fetching

TanStack Query (React Query) - Server state management
React Hooks - Local state management

UI Components & Libraries

shadcn/ui - Re-usable component library
dnd-kit - Drag-and-drop functionality
date-fns - Date manipulation
sonner - Toast notifications
cmdk - Command palette
next-themes - Dark mode support

Authentication & Security

Clerk - User authentication and organization management
Token Encryption - Secure OAuth token storage

Testing

Vitest - Unit and integration testing
Testing Library - React component testing
MSW (Mock Service Worker) - API mocking

Developer Tools

ESLint - Code linting
PostCSS - CSS processing

📦 Prerequisites

Before setting up the project, ensure you have:

Node.js 20.x or higher
npm 9.x or higher (comes with Node.js)
PostgreSQL database (or a Neon account for hosted PostgreSQL)
Clerk Account for authentication setup
Git for version control

Optional Integrations

Jira Account - For Jira integration features
GitHub Account - For GitHub integration features
Slack Workspace - For notification features

⚡ Quick Start (5-10 minutes)

Want to get the app running quickly for local development? Follow these streamlined steps:

# 1. Clone and install
git clone <repository-url>
cd release-coordinator
npm install

# 2. Copy environment template
cp .env.example .env

# 3. Edit .env and add your credentials:
#    - DATABASE_URL: Get a free database at https://neon.tech
#    - CLERK keys: Get from https://clerk.com (create account + app)
#    - TOKEN_ENCRYPTION_KEY: Run: openssl rand -base64 32

# 4. Set up database
npx prisma db push

# 5. Start development server
npm run dev

Open http://localhost:3000 to see the app!

Note: This Quick Start uses minimal configuration. Clerk webhooks and OAuth integrations can be configured later. See the Full Setup Instructions below for production-ready configuration.

🚀 Full Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd release-coordinator

2. Install Dependencies

npm install

This will install all required packages and automatically run prisma generate via the postinstall script.

3. Set Up Environment Variables

Copy the example environment file and fill in your values:

cp .env.example .env

Important: Generate your TOKEN_ENCRYPTION_KEY first (see Step 7 below) before completing your .env file.

Or create a .env file manually with the following variables:

# Database (Neon PostgreSQL)
DATABASE_URL="postgresql://username:password@host/database?sslmode=require"

# Clerk Authentication (Required)
CLERK_WEBHOOK_SECRET=your_webhook_secret
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key
CLERK_SECRET_KEY=your_secret_key

# Clerk URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/board
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/select-org

# Token Encryption (Required)
# Generate with: openssl rand -base64 32
TOKEN_ENCRYPTION_KEY=your_generated_encryption_key

# Jira OAuth (Optional)
JIRA_CLIENT_ID=your_jira_client_id
JIRA_CLIENT_SECRET=your_jira_client_secret

# GitHub OAuth (Optional)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

See the Environment Variables section below for detailed setup instructions.

4. Set Up the Database

Generate Prisma client and run migrations:

# Generate Prisma client
npx prisma generate

# Push the schema to your database
npx prisma db push

# (Optional) Seed the database with sample data
npx prisma db seed

Alternatively, you can use Prisma migrations:

npx prisma migrate dev --name init

5. Configure Clerk

Create a Clerk application at clerk.com
Enable organizations in your Clerk dashboard
Copy your API keys to the .env file:
- NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
- CLERK_SECRET_KEY
- CLERK_WEBHOOK_SECRET

For Local Development: You can skip webhook configuration initially and set it up later when deploying. The app will run without webhooks, but user and organization sync features will be limited.

For Production: Set up the webhook endpoint for full functionality:

Deploy your application and get your public URL
In Clerk dashboard, add webhook endpoint: https://your-domain/api/webhooks/clerk
Configure the following webhook events:
- user.created
- user.updated
- organization.created
- organization.updated
- organizationMembership.created
For local development with webhooks, use ngrok to expose your local server

6. (Optional) Configure OAuth Integrations

Jira OAuth Setup

Create an OAuth 2.0 app in Atlassian Developer Console
Set redirect URI: https://your-domain/api/oauth/jira/callback
Add scopes: read:jira-work, read:jira-user
Copy Client ID and Secret to .env

GitHub OAuth Setup

Create an OAuth App in GitHub Settings → Developer settings
Set authorization callback URL: https://your-domain/api/oauth/github/callback
Copy Client ID and Secret to .env

7. Generate Encryption Key

Generate a secure encryption key for OAuth token storage:

openssl rand -base64 32

Add the generated key to your .env file as TOKEN_ENCRYPTION_KEY.

8. Run the Development Server

npm run dev

Open http://localhost:3000 in your browser to see the application.

9. Create Your First Organization

Sign up for an account at /sign-up
Create your first organization at /select-org
Start managing releases!

10. (Optional) Configure Slack Notifications

In the team settings, add your Slack webhook URL to receive notifications for:

Release status changes
Blocked releases
Releases ready to deploy

✅ Verify Your Setup

After completing the setup steps, verify everything is working correctly:

1. Check Database Connection

Open Prisma Studio to confirm your database is properly configured:

npx prisma studio

This should open a browser window at http://localhost:5555 showing your database tables.

2. Build the Application

Verify the application builds without errors:

npm run build

You should see a successful build output with no TypeScript or build errors.

3. Run Development Server

Start the development server:

npm run dev

You should see output indicating the server is running on http://localhost:3000.

4. Access the Application

Open http://localhost:3000 in your browser. You should see:

The Clerk sign-in page if authentication is configured correctly
No console errors in the browser developer tools

5. Run Tests

Verify the test suite passes:

npm run test:run

All tests should pass with no errors.

Common Issues

"Error: DATABASE_URL not found"

Ensure your .env file exists in the root directory
Verify DATABASE_URL is set correctly
Try restarting the development server

"Clerk keys are not valid"

Double-check your Clerk keys in the .env file
Ensure you're using the correct keys for your Clerk application
Verify there are no extra spaces or quotes

"Port 3000 is already in use"

Stop any other processes using port 3000
Or specify a different port: PORT=3001 npm run dev

"Prisma Client did not initialize"

Run npx prisma generate manually
Delete node_modules/.prisma and run npm install again

Webhook events not working locally

Clerk webhooks require a public URL
Use ngrok to expose your local server: ngrok http 3000
Update the webhook URL in Clerk dashboard to your ngrok URL

For more help, see our Troubleshooting Guide.

🔐 Environment Variables Guide

Required Variables

Database Configuration

DATABASE_URL - PostgreSQL connection string
- Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require
- Provider: Neon (recommended) or any PostgreSQL provider
- Example: Get a free database at neon.tech

Clerk Authentication

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Public key for client-side Clerk integration
CLERK_SECRET_KEY - Secret key for server-side Clerk operations
CLERK_WEBHOOK_SECRET - Secret for verifying webhook authenticity
NEXT_PUBLIC_CLERK_SIGN_IN_URL - Sign-in page URL (default: /sign-in)
NEXT_PUBLIC_CLERK_SIGN_UP_URL - Sign-up page URL (default: /sign-up)
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL - Redirect after sign-in (default: /board)
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL - Redirect after sign-up (default: /select-org)

Security

TOKEN_ENCRYPTION_KEY - 32-byte base64 key for encrypting OAuth tokens
- Generate: openssl rand -base64 32
- Important: Keep this secure and never commit to version control

Optional Variables

Jira Integration

JIRA_CLIENT_ID - OAuth 2.0 client ID from Atlassian Developer Console
JIRA_CLIENT_SECRET - OAuth 2.0 client secret

GitHub Integration

GITHUB_CLIENT_ID - OAuth App client ID from GitHub
GITHUB_CLIENT_SECRET - OAuth App client secret

🗄 Database Setup

Using Neon (Recommended)

Create a free account at neon.tech
Create a new project and database
Copy the connection string (with pooling enabled)
Add to .env as DATABASE_URL
Run npx prisma db push to create tables

Using Local PostgreSQL

Install PostgreSQL on your machine
Create a new database:
```
createdb release_coordinator
```

Update DATABASE_URL in .env:

DATABASE_URL="postgresql://postgres:password@localhost:5432/release_coordinator"

Run npx prisma db push to create tables

Database Schema

The application uses the following main entities:

Team - Organizations/workspaces
User - Application users (synced with Clerk)
Service - Software services/repositories
Sprint - Time-boxed planning periods
Release - Individual release records
DeploymentGroup - Grouped releases with deployment orchestration
ReleaseItem - PRs, tickets, and tasks within releases
OAuthConnection - Encrypted third-party integration tokens

💻 Development Commands

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linting
npm run lint

# Generate Prisma client
npx prisma generate

# Open Prisma Studio (database GUI)
npx prisma studio

# Push schema changes to database
npx prisma db push

# Create and apply migrations
npx prisma migrate dev

# Run tests
npm test

# Run tests in watch mode
npm run test

# Run tests with coverage
npm run test:coverage

# Run tests once (CI mode)
npm run test:run

🧪 Testing

The project uses Vitest for testing with React Testing Library:

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests once (no watch mode)
npm run test:run

Test files are located in:

src/test/ - Test setup and utilities
**/*.test.ts or **/*.test.tsx - Component and unit tests

📚 Documentation

Comprehensive documentation is available to help you understand and work with Release Coordinator:

Architecture Guide - System design, data models, integration flows, and design decisions
User Guide - Complete feature documentation for teams, releases, sprints, and integrations
API Reference - REST API documentation with request/response schemas and examples
Development Guide - Project structure, coding conventions, and development workflows

📁 Project Structure

release-coordinator/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── (auth)/            # Authentication pages
│   │   ├── (dashboard)/       # Main application pages
│   │   ├── api/               # API routes
│   │   └── select-org/        # Organization selection
│   ├── components/            # React components
│   │   ├── ui/               # shadcn/ui components
│   │   └── ...               # Feature components
│   ├── lib/                   # Utilities and helpers
│   ├── test/                  # Test setup and utilities
│   └── middleware.ts          # Clerk authentication middleware
├── prisma/
│   └── schema.prisma          # Database schema
├── public/                    # Static assets
├── .env                       # Environment variables (not committed)
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── tailwind.config.ts         # Tailwind CSS configuration
└── vitest.config.ts           # Test configuration

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes following our code standards
Write or update tests as needed
Commit your changes with clear messages
Push to your fork and submit a pull request

Code Standards

TypeScript: Use strict typing, avoid any when possible
Components: Use functional components with hooks
Formatting: Follow the existing code style (enforced by ESLint)
Naming: Use clear, descriptive names for variables and functions
Comments: Document complex logic and non-obvious decisions
Tests: Write tests for new features and bug fixes

Commit Messages

Use clear, descriptive commit messages:

feat: add release dependency tracking
fix: correct deployment group ordering
docs: update setup instructions
test: add coverage for sprint API
refactor: simplify release status logic

Pull Request Process

Update documentation if you change functionality
Ensure all tests pass: npm run test:run
Ensure no linting errors: npm run lint
Update the README if needed
Request review from maintainers
Address any review feedback

Reporting Issues

When reporting bugs, please include:

Clear description of the issue
Steps to reproduce
Expected vs actual behavior
Browser/environment information
Screenshots if applicable

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Need help? Here's where to find it:

Documentation: See the 📚 Documentation section above for comprehensive guides
Troubleshooting: Check the Troubleshooting Guide for common issues
User Guide: See docs/USER_GUIDE.md for feature-specific help
Issues: Report bugs or request features via your project's issue tracker

🙏 Acknowledgments

Built with:

Next.js - The React Framework
Clerk - Authentication and User Management
Prisma - Next-generation ORM
Neon - Serverless PostgreSQL
shadcn/ui - Component Library
Tailwind CSS - CSS Framework
Radix UI - Accessible Components

Release Coordinator - Streamline your software deployments with confidence.

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
docs		docs
prisma		prisma
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation