Getting Started¶

This guide walks you through setting up Ospobox and adding your first organization to monitor.

Prerequisites¶

Before you begin, ensure you have:

• Ospobox running (see Installation)
• An account on the platform you want to monitor (GitHub/GitLab)
• Admin access to the organizations you want to monitor (for private repositories)

Step 1: Create an Account¶

1. Open Ospobox in your browser
2. Click Register on the login page
3. Fill in your details:
4. Name: Your display name
5. Email: Your email address
6. Password: A secure password (minimum 8 characters)
7. Click Create Account

Step 2: Add Your First Organization¶

After logging in, you'll see the dashboard. Let's add an organization:

1. Click Add Organization in the sidebar or on the empty dashboard
2. Select the platform (GitHub or GitLab)
3. Enter the organization name (e.g., python for github.com/python)
4. Choose whether it's external (an organization you don't own)
5. Click Add Organization

graph TD
    A[Dashboard] --> B[Add Organization]
    B --> C{Choose Platform}
    C --> D[GitHub]
    C --> E[GitLab]
    D --> F[Enter Org Name]
    E --> F
    F --> G[Sync Started]
    G --> H[View Activity]

Step 3: Wait for Initial Sync¶

After adding an organization, Ospobox will:

1. Fetch the list of repositories
2. Retrieve recent commits, pull requests, and issues
3. Calculate health scores for each repository

Step 4: Explore the Dashboard¶

Once the sync completes, explore your data:

Organization Overview¶

Click on an organization to see:

• Repository list with health scores
• Recent activity summary
• Contributor breakdown
• Sync status and history

Repository Details¶

Click on a repository to see:

• Health score breakdown
• Commit history
• Pull request status
• Top contributors

Activity Feed¶

The main dashboard shows recent activity across all organizations:

• Latest commits
• New pull requests
• Issues opened/closed
• Health score changes

Step 5: Check Your Alerts¶

There is nothing to configure: alerts are generated automatically after each sync. Open Alerts in the sidebar to see what the first pass found: inactive repositories, low health scores, PR and issue backlogs, and sharp week-over-week drops.

The first pass over a new account is usually noisy, because every quiet repository trips the low-health rule once. Acknowledge that batch and later passes stay quiet.

See Alerts for the rules and their thresholds.

Step 6: Generate a Report (Optional)¶

Create a report summarizing activity:

1. Go to Reports in the navigation
2. Select the date range (7, 30, or 90 days)
3. Choose which organizations to include
4. Select report sections:
5. Activity summary
6. Health scores
7. Top contributors
8. Pull request status
9. Click Generate Report
10. Download as Markdown or PDF, or email directly

Next Steps¶

Now that you're set up, explore more features:

• Organizations - Managing monitored organizations
• Reports - Creating and customizing reports
• Alerts - Setting up notifications
• API Reference - Automate with the API

Troubleshooting¶

Organization not syncing¶

• Check that the organization name is correct
• For private organizations, ensure you've connected your OAuth account
• Look for error messages on the organization detail page

No activity showing¶

• Verify the organization has recent activity
• Check that repositories aren't archived
• Wait for the sync to complete

Health scores are low¶

Health scores consider:

• Recent commit activity
• Pull request activity
• Number of contributors
• Issue response times

See the repository detail page for a breakdown of what's affecting the score.