Skip to main content

Development Guide

Complete guide for setting up, developing, and deploying the Gamuda Technology Jira Tracker.

📋 Table of Contents​

Prerequisites​

Required Software​

  • Node.js >= 18.0.0
  • npm >= 9.0.0
  • Git
  • Google Cloud SDK (gcloud CLI)
  • Terraform >= 1.0.0

Required Accounts​

  • Google Cloud Platform account with billing enabled
  • Firebase project
  • Jira account with API access
  • Bitbucket account with API access

Local Development Setup​

1. Clone the Repository​

git clone https://github.com/gamuda-tech/jira-tracker.git
cd jira-tracker

2. Install Dependencies​

npm install

3. Set Up Environment Variables​

Copy the example environment file:

cp env.example .env.local

Edit .env.local with your configuration:

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id

# Firebase Admin SDK (Server-side)
FIREBASE_SERVICE_ACCOUNT_PATH=./firebase-service-account.json

# Jira Configuration
JIRA_BASE_URL=https://your-domain.atlassian.net/
NEXT_PUBLIC_JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token

# Bitbucket Configuration
BITBUCKET_USERNAME=your-email@company.com
BITBUCKET_API_TOKEN=your-bitbucket-api-token
BITBUCKET_WORKSPACE=your-workspace-name

Firebase Setup​

1. Create a Firebase Project​

  1. Go to Firebase Console
  2. Click "Add project"
  3. Follow the setup wizard

2. Enable Firestore​

  1. In Firebase Console, go to "Firestore Database"
  2. Click "Create database"
  3. Choose "Start in production mode"
  4. Select a location (e.g., asia-southeast1)

3. Enable Authentication​

  1. Go to "Authentication" → "Sign-in method"
  2. Enable "Email/Password"

4. Get Firebase Admin Service Account​

  1. Go to Project Settings → Service Accounts
  2. Click "Generate new private key"
  3. Save the JSON file as firebase-service-account.json in the project root
  4. Important: This file is gitignored - never commit it!

5. Deploy Firestore Rules and Indexes​

npm install -g firebase-tools
firebase login
firebase use --add  # Select your project
firebase deploy --only firestore:rules
firebase deploy --only firestore:indexes

Configuration Files​

Project Mappings (configs/project-mappings.json)​

Maps Bitbucket repositories to Jira projects:

{
  "bitbucketToJira": {
    "my-repo-slug": "JIRA-PROJECT-KEY",
    "another-repo": "ANOTHER-KEY"
  }
}

To auto-generate mappings from your Bitbucket workspace:

node scripts/fetch-bitbucket-repos.js

Team Configuration (configs/team-config.json)​

Organizes engineers into teams:

{
  "teams": [
    {
      "name": "Delivery - Software - Product Team 1",
      "members": [
        {
          "name": "Engineer Name",
          "emails": ["email@company.com"],
          "accountIds": ["jira-account-id"]
        }
      ]
    }
  ]
}

To auto-generate team config from Jira:

node scripts/generate-team-config-from-jira.js

Running the Application​

Development Server​

npm run dev

Open http://localhost:3000

Build for Production​

npm run build
npm start

Available Commands​

  • npm run dev - Start development server
  • npm run build - Build for production
  • npm run start - Start production server
  • npm run lint - Lint code
  • npm run typecheck - Check TypeScript types

Deployment​

Deploy to Google Cloud Run​

1. Set Up Google Cloud Project​

# Login to Google Cloud
gcloud auth login

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Enable required APIs
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable cloudscheduler.googleapis.com

2. Set Up Secrets in Secret Manager​

Run the setup script:

./setup-secrets.sh

This will prompt you for:

  • Jira credentials
  • Bitbucket credentials
  • Firebase service account JSON

3. Deploy the Application​

./deploy-to-gcp.sh

This will:

  • Build the Docker image
  • Push to Google Container Registry
  • Deploy to Cloud Run
  • Configure environment variables

4. Set Up Automated Sync with Terraform​

cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values

terraform init
terraform plan
terraform apply

This creates:

  • Cloud Scheduler job (runs daily at 1 AM)
  • Service account with proper permissions
  • IAM bindings

Automated Sync​

How It Works​

The system automatically syncs data from Jira and Bitbucket every day at 1 AM (configurable).

What gets synced:

  • Jira issues updated in the last 24 hours
  • Jira worklogs from the last 24 hours
  • Bitbucket commits from the last 24 hours
  • Bitbucket pull requests created/updated in the last 24 hours
  • Lines of code changed (diffstat)

What gets computed:

  • Engineer metrics (per engineer, per day)
  • Project metrics (per project, per day)
  • Daily snapshots (company-wide)
  • Correlation between Jira issues and Bitbucket activity

Manual Sync​

You can trigger a manual sync from the UI:

  1. Go to /settings
  2. Click "Start Sync"
  3. Choose the number of days to sync back

Or trigger via Cloud Scheduler:

gcloud scheduler jobs run daily-jira-bitbucket-sync --location=asia-southeast1

Sync Performance​

  • Daily sync (1 day): 1-2 minutes
  • Weekly sync (7 days): 3-5 minutes
  • Monthly sync (30 days): 5-10 minutes

Troubleshooting​

Common Issues​

1. Firebase Admin SDK Errors​

Error: Service account file not found

Solution:

  • Ensure firebase-service-account.json exists in the project root
  • Check that FIREBASE_SERVICE_ACCOUNT_PATH is set correctly in .env.local

2. Jira API Errors​

Error: 401 Unauthorized

Solution:

  • Verify your Jira API token is valid
  • Check that JIRA_USERNAME matches the account that created the token
  • Ensure the token has the required permissions

3. Bitbucket Rate Limiting​

Error: 429 Too Many Requests

Solution:

  • The system automatically handles rate limiting
  • For manual syncs, use shorter date ranges (1-7 days)
  • Diffstat fetching is automatically disabled for longer syncs

4. Firestore Permission Errors​

Error: Missing or insufficient permissions

Solution:

  • Deploy Firestore rules: firebase deploy --only firestore:rules
  • Check that the service account has Firestore permissions
  • Verify indexes are deployed: firebase deploy --only firestore:indexes

Logs and Monitoring​

View Cloud Run Logs​

gcloud run services logs read gamuda-jira-tracker \
  --region=asia-southeast1 \
  --limit=100

View Cloud Scheduler Logs​

gcloud scheduler jobs describe daily-jira-bitbucket-sync \
  --location=asia-southeast1

Check Sync History​

Go to /settings in the application to view sync history and results.

Development Workflow​

Making Changes​

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes

  3. Test locally:

    npm run dev
    npm run lint
    npm run typecheck

  4. Commit and push:

    git add .
    git commit -m "Description of changes"
    git push origin feature/your-feature-name

  5. Deploy to production:

    ./deploy-to-gcp.sh

Database Schema​

The application uses Firestore with the following collections:

  • users - User accounts and profiles
  • issues - Jira issues
  • worklogs - Jira worklogs
  • commits - Bitbucket commits
  • pullRequests - Bitbucket pull requests
  • projects - Jira project metadata
  • engineerMetrics - Aggregated engineer metrics (per day)
  • projectMetrics - Aggregated project metrics (per day)
  • dailySnapshots - Company-wide daily snapshots
  • config - Application configuration (auto-sync settings, etc.)

Support​

For issues or questions:

License​

Private - Gamuda Technology