# Guidelines Source: https://omnilens-626cb878.mintlify.app/contributing/guidelines How to contribute to OmniLens ## Forking 1. Navigate to the [OmniLens repository](https://github.com/omnilens/OmniLens) on GitHub 2. Click the `Fork` button in the top-right corner of the repository page 3. Select your GitHub account or organization as the destination for the fork 4. Wait for GitHub to create your fork 5. Clone your fork locally: ```bash theme={null} git clone https://github.com/YOUR_USERNAME/OmniLens.git ``` 6. Add the upstream repository: ```bash theme={null} git remote add upstream https://github.com/omnilens/OmniLens.git ``` ## Pull Requests * Ensure your PR adheres to the provided template * PRs will not be looked at until **all** automated checks have successfully passed # Test Suites Source: https://omnilens-626cb878.mintlify.app/contributing/testing An overview of the available test suites # Frameworks We use the following frameworks: * **E2E tests:** Playwright * **API integration tests:** Bun (functional tests) # Running tests ## API Integration tests Bun integration tests are located in `tests/` (root directory) and test API endpoints with real database connections. ```bash theme={null} # Run all integration tests bun run test # Run specific tests bun run test:health bun run test:auth:basic bun run test:github-status ``` ## E2E tests E2E tests are located in `e2e/tests/` and test the full application flow in a real browser environment. > **Note:** Playwright browsers are automatically installed via `postinstall` script when dependencies are installed. **Prerequisites:** * Set up environment variables in `e2e/.env` (see `e2e/README.md` for details) * Ensure PostgreSQL database is running and schema is initialized ```bash theme={null} # Run all E2E tests bun run test:e2e # Run smoke tests only bun run test:e2e:login # Run with UI (interactive) bun run test:e2e:ui # Run in debug mode bun run test:e2e:debug # Run in headed mode (see browser) bun run test:e2e:headed ``` > **Note:** Before running other E2E tests, authenticate first by running `bun run test:e2e:auth-setup` to save authenticated state. # GitHub Actions Each test suite has a corresponding GitHub Action workflow which run daily. Each workflow supports `workflow_dispatch`, which enables manual runs against committed branches. # Welcome Source: https://omnilens-626cb878.mintlify.app/home OmniLens is an open-source platform for **visualizing and tracking** GitHub Actions workflow health. Designed to: * **Ingest workflow signals** from tests, checks, and jobs * **Track** health and consistency across workflow runs * **Clearly surface** what’s healthy, regressing, or inactive ## Features ### Repository Management Add, validate, and manage repositories within your dashboard to monitor workflow health. ### Workflow History Explore workflow runs across specific dates using a clear, calendar-based history view. ### Metrics & State Track workflow health using success rates, run counts, runtimes, and stability trends over time. # Database Schema Source: https://omnilens-626cb878.mintlify.app/self-hosting/database OmniLens uses PostgreSQL to store repository and workflow data. ## Tables The database contains two main tables: * **`repositories`**: Stores repository information, metadata, and user-added repos * **`workflows`**: Stores workflow definitions and metadata for persistence ### Repositories Table * `id`: Primary key * `slug`: Unique repository identifier (owner-repo format) * `repo_path`: Full repository path (owner/repo) * `display_name`: Human-readable repository name * `html_url`: GitHub repository URL * `default_branch`: Repository's default branch * `avatar_url`: Repository owner's avatar * `added_at`: Timestamp when added * `updated_at`: Last updated timestamp ### Workflows Table * `id`: Primary key * `repo_slug`: Foreign key to repositories * `workflow_id`: GitHub workflow ID * `workflow_name`: Workflow display name * `workflow_path`: Workflow file path * `workflow_state`: Active/disabled state * `created_at`: Timestamp when first saved * `updated_at`: Last updated timestamp ## Database Commands ### List all tables ```bash theme={null} psql -d omnilens -c "\dt" ``` ### View table structure ```bash theme={null} psql -d omnilens -c "\d repositories" psql -d omnilens -c "\d workflows" ``` ### Preview table data ```bash theme={null} psql -d omnilens -c "SELECT * FROM repositories LIMIT 5;" psql -d omnilens -c "SELECT * FROM workflows LIMIT 5;" ``` # Overview Source: https://omnilens-626cb878.mintlify.app/self-hosting/overview An overview on how to self-host OmniLens ## Prerequisites * Node.js 18+ or Bun * PostgreSQL (any installation method) * GitHub Personal Access Token with `repo` scope ## Clone the repository ```bash theme={null} git clone https://github.com/your-username/omnilens.git cd omnilens ``` ## Install dependencies ```bash theme={null} bun install ``` ## Set up database The setup script automatically detects your PostgreSQL installation: ```bash theme={null} bun run setup ``` ## Configure environment variables Copy the example file: ```bash theme={null} cp .env.example .env ``` Then update `.env` with your GitHub token and database configuration. ## Set up GitHub OAuth App * Go to [GitHub Settings > Developer settings > OAuth Apps](https://github.com/settings/developers) * Create a new OAuth App with: * Homepage URL: `http://localhost:3000` * Authorization callback URL: `http://localhost:3000/api/auth/callback/github` * Copy the Client ID and Client Secret to your `.env` ## Start the development server ```bash theme={null} bun dev ``` Navigate to [http://localhost:3000](http://localhost:3000) ## Linting ```bash theme={null} bun run lint ``` # Authentication Source: https://omnilens-626cb878.mintlify.app/using-omnilens/auth 1. Navigate to the Login page and click the `Continue with GitHub` button 2. Authorize the OmniLens OAuth app Once authenticationed, you'll be automatically redirected to your Dashboard. If you are not signed into GitHub, you will be prompted by GitHub to first sign in. # GitHub Actions status Source: https://omnilens-626cb878.mintlify.app/using-omnilens/github-actions-status OmniLens automatically monitors GitHub Actions status and displays a banner at the top of your dashboard when GitHub is experiencing outages. This helps you quickly determine if workflow failures are due to GitHub's infrastructure issues rather than problems with your code. `insert image here <(''<)` ## Banner Information The banner shows: * **Status level**: Orange for partial outages, red for major outages * **Status message**: Brief explanation of what's happening * **Last updated**: When the status was last refreshed (e.g., "Just now", "5m ago") ## Banner Controls Three buttons help you manage the banner: * **Refresh** - Check for the latest status update * **External Link** - Open GitHub's official status page for detailed information * **Dismiss** - Hide the banner (it reappears if you refresh the page and the issue persists) # Home Dashboard Source: https://omnilens-626cb878.mintlify.app/using-omnilens/home-dashboard ## Overview The Home page provides a single view of all your repository cards as well as the ability to add more. Home ## Add a Repository Card Enter a GitHub repository URL or `owner/repo` format in the add repository dialog. Add Repo OmniLens will: 1. **Validation**: Verifies the repository exists and you have access to it 2. **Addition**: Adds the repository card to your dashboard 3. **Data Fetching**: Discovers and fetches workflow definitions to display initial run data You can add up to 12 public repository cards to your dashboard. ## Repository Card Overview Each repository card provides a compact overview of your repository's workflow activity. Repo Card ### Metrics The repository card displays the following metrics: * **Daily Success Rate**: A progress bar showing the percentage of successful workflow runs * **Total Workflows**: The number of workflows configured in the repository * **Passed Runs**: Count of workflow runs that completed successfully * **Failed Runs**: Count of workflow runs that failed * **In Progress Runs**: Count of workflow runs currently running ### Actions Each repository card includes interactive elements: * **GitHub icon**: Navigate directly to the repository on GitHub in a new tab * **Trash can icon**: Remove the repository card and all its associated data from your dashboard # Repository Dashboard Source: https://omnilens-626cb878.mintlify.app/using-omnilens/repo-dashboard ## Summary The Summary page provides a detailed view of workflow runs and metrics for your repository. Repo Dash ### Date Selection You can view workflow runs for any date by using the date controls in the top-right corner: * **Today button**: Quickly jump to today's date * **Calendar picker**: Select any date to view historical workflow runs * **Refresh button**: Reload the page to fetch the latest data ### Daily Metrics There are four metric cards showing aggregated statistics for the selected date. * **Pass/Fail Rate**: A pie chart showing the success rate of workflow runs * **Overview**: General statistics * **Workflow Health**: Health status breakdown comparing today's runs with yesterday's * **Runs by hour**: A bar chart showing when workflows are most active throughout the day ### Workflow section The workflow cards are split in two sections: * **Active Workflows**: Workflows that have runs for the selected date * **Idle Workflows**: Workflows that have no runs for the selected date ## Workflow Card Overview Each workflow card provides a compact overview of the workflow's activity. Workflow Card ### Metrics The workflow card displays the following metrics: * **Status badge**: Visual indicator showing Pass, Fail, Running, or Idle * **Run count badge**: Shows when a workflow runs multiple times * **Health status indicator**: Compares today's performance with yesterday * **Duration**: The total runtime of the workflow execution ### Actions Each workflow card includes interactive elements: * **View button**: Opens the workflow run on GitHub Actions * **Run count badge**: Click to view all runs Workflow Runs