ReleaseFlow - DevOps Release Orchestrator

ReleaseFlow is a Next.js application designed to help manage and visualize DevOps release processes, particularly focusing on Git branch merging strategies across multiple repositories.

Getting Started

Prerequisites

• Node.js (v18 or later recommended)
• npm or yarn
• A Firebase project

1. Clone the Repository

git clone <your-repository-url>
cd <repository-name>

2. Install Dependencies

npm install
# or
yarn install

3. Set up Firebase

1. Create a Firebase Project:

   • Go to the Firebase Console.
   • Click on "Add project" and follow the instructions.

2. Enable Google Authentication:

   • In your Firebase project console, go to "Authentication" (under Build).
   • Click on the "Sign-in method" tab.
   • Find "Google" in the list of providers and click the pencil icon to edit.
   • Enable the Google provider.
   • Ensure you select your project's support email.
   • Click "Save".

3. Set up Firestore Database:

   • In your Firebase project console, go to "Firestore Database" (under Build).
   • Click "Create database".
   • Choose Start in production mode.
   • Select a Firestore location (choose one close to your users).
   • Click "Enable".

4. Register your Web App with Firebase:

   • In your Firebase project console, go to Project Settings (click the gear icon next to "Project Overview").
   • Scroll down to "Your apps".
   • Click on the Web icon (</>) to add a new web app.
   • Give your app a nickname (e.g., "ReleaseFlow Web").
   • Do NOT check "Also set up Firebase Hosting for this app" unless you plan to use Firebase Hosting for this specific Next.js app (this starter is configured for App Hosting or other Node.js environments).
   • Click "Register app".

5. Get Firebase Configuration:

   • After registering, Firebase will provide you with a firebaseConfig object. Copy these values.

4. Configure Environment Variables

Create a .env.local file in the root of your project and add your Firebase configuration keys:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# For Genkit AI features (if used) - Optional
# NEXT_PUBLIC_GOOGLE_GENERATIVE_AI_API_KEY=your_google_ai_api_key

Replace your_... with the actual values from your Firebase project settings.

5. Firestore Security Rules

It is CRITICAL to set up proper Firestore security rules to protect your data. Users should only be able to access their own data.

• Go to your Firebase project console -> Firestore Database -> Rules.
• Update the rules. Here's an example to get started, ensuring users can only manage their own app definitions and releases they trigger:

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {

    // Users can only read/write their own app definitions.
    match /apps/{appId} {
      allow read: if request.auth != null && resource.data.ownerUid == request.auth.uid;
      allow list: if request.auth != null && request.query.resource.data.ownerUid == request.auth.uid; // For querying user's apps
      allow create: if request.auth != null && request.resource.data.ownerUid == request.auth.uid;
      allow update: if request.auth != null && resource.data.ownerUid == request.auth.uid;
      allow delete: if request.auth != null && resource.data.ownerUid == request.auth.uid;
    }

    // Users can only read/write releases associated with their apps or triggered by them.
    // This rule allows a user to read any release if they are authenticated (for dashboard view)
    // but restricts create/update/delete to the user who triggered it OR owns the app.
    match /releases/{releaseId} {
      allow read: if request.auth != null; // Allows any authenticated user to read release details for simplicity.
                                        // For stricter access, you might query based on app ownership.
      allow create: if request.auth != null && request.resource.data.triggeredByUid == request.auth.uid;
      // Update logic can be complex. For now, allow if user is authenticated.
      // You might want to restrict updates to specific fields or system roles.
      allow update: if request.auth != null && (resource.data.triggeredByUid == request.auth.uid); 
                      // Or check if the user owns the app:
                      // get(/databases/$(database)/documents/apps/$(resource.data.appId)).data.ownerUid == request.auth.uid
      allow delete: if false; // Typically, releases are not deleted by users.
    }
  }
}

Important: These are example rules. You must refine them based on your application's specific requirements and security needs. Test your rules thoroughly using the Firebase console simulator. For example, for listing apps, you might need a rule on the apps collection like: allow list: if request.auth != null && request.query.filters.find(f => f.fieldPath == "ownerUid" && f.value == request.auth.uid) != null; or ensure queries always include where('ownerUid', '==', request.auth.uid). The rule allow list: if request.auth != null && request.query.resource.data.ownerUid == request.auth.uid; is an illustrative attempt and might need adjustment based on how Firestore evaluates list queries. The key is to ensure queries from data-service.ts are compatible with these rules.

6. Run the Development Server

npm run dev
# or
yarn dev

Open http://localhost:9002 (or the port specified in package.json) with your browser to see the result. You should be prompted to log in with Google.

7. Genkit AI Features (Optional)

If you plan to use the AI features (like the Merge Recommender):

1. Make sure you have a Google AI API key.
2. Add it to your .env.local file as NEXT_PUBLIC_GOOGLE_GENERATIVE_AI_API_KEY.
3. Ensure the Genkit development server is running if you are actively developing AI flows:

   npm run genkit:dev

Project Structure

• src/app/: Next.js App Router pages.
• src/components/: Shared React components.
  • src/components/ui/: ShadCN UI components.
  • src/components/layout/: Layout components like Header, Footer.
  • src/components/apps/: Components specific to app definitions.
  • src/components/releases/: Components specific to releases.
• src/hooks/: Custom React hooks (e.g., useAuth, useToast).
• src/lib/: Utility functions, Firebase setup, data services.
  • src/lib/firebase.ts: Firebase initialization.
  • src/lib/data-service.ts: Firestore data interaction logic.
  • src/lib/utils.ts: General utility functions (like cn for Tailwind).
• src/ai/: Genkit related files.
  • src/ai/flows/: Genkit flow definitions.
  • src/ai/genkit.ts: Genkit global instance.
• src/types/: TypeScript type definitions.
• public/: Static assets.
• globals.css: Global styles and Tailwind CSS setup.
• tailwind.config.ts: Tailwind CSS configuration.

Data Model (Firestore Collections)

• apps: Stores AppDefinition objects. Each document represents an application configuration.
  • ownerUid: Links to the Firebase Auth UID of the user who owns the app. (Crucial for security rules)
  • appName: Name of the application.
  • repositories: Array of AppRepository objects.
  • createdAt: Timestamp of creation.
• releases: Stores Release objects. Each document represents a release process.
  • appId: ID of the app this release belongs to.
  • appName: Denormalized app name.
  • status: Current status of the release (e.g., 'in-progress', 'completed').
  • createdAt: Timestamp of initiation.
  • triggeredByUid: Firebase Auth UID of the user who initiated the release. (Crucial for security rules)
  • stages: Array of ReleaseStageExecution objects detailing each step of the release.

Securely Handling GitHub Credentials

This application framework is set up for user authentication via Google. If you intend to perform actions on behalf of the user on GitHub (e.g., merging branches, creating PRs), you will need to handle GitHub Personal Access Tokens (PATs) or GitHub App credentials.

Storing PATs directly in Firestore from the client-side is NOT recommended due to security risks.

Consider the following approaches for more secure GitHub integration:

1. Firebase Functions: Create Firebase Functions that act as a backend.
   • Users could authorize your application via OAuth2 with GitHub.
   • The Firebase Function would securely store the OAuth token (or a PAT if absolutely necessary, with very limited scopes) associated with the user's Firebase UID.
   • All GitHub API calls would be proxied through this Firebase Function, which would attach the necessary authentication.
2. GitHub Apps: For more robust and secure integration, especially for organizational use, consider creating a GitHub App. This provides more granular permissions and better management than user PATs.

Next Steps & Further Development

• GitHub Integration:
  • Implement a secure method for handling GitHub authentication (see "Securely Handling GitHub Credentials" above).
  • Implement logic to fetch PR details, create PRs, merge branches via GitHub API using the authenticated context.
  • Set up webhooks from GitHub to update release stage statuses automatically (would require a backend endpoint, possibly a Firebase Function).
• Advanced Release Management:
  • Implement approval steps for stages.
  • Allow rollback or retry of failed stages.
  • More detailed logging for each stage.
• Notifications: Inform users about release progress or failures.
• Enhanced AI Features: Expand AI capabilities for more complex suggestions or automated tasks.
• Testing: Add unit and integration tests.

This README provides a comprehensive guide to getting your ReleaseFlow application connected to Firebase with Google Authentication. Remember to regularly review and update your Firestore security rules as your application evolves.