Skip to content

README.md

Latest commit

 

History

History
333 lines (245 loc) · 10.9 KB

README.md

File metadata and controls

333 lines (245 loc) · 10.9 KB
Raw

Konveyor Stale Issues Dashboard

A Grafana-inspired dashboard for monitoring stale issues and pull requests across Konveyor repositories.

Features

  • Real-time data fetched from GitHub API
  • Historical Trends: Automated collection and visualization of stale items over time
  • Close Stale Items: Close issues and PRs directly from the dashboard with customizable closing messages
  • Filter by repository, type (issue/PR), and search by title
  • Sortable columns
  • Statistics overview with trend charts
  • Dark theme inspired by Grafana
  • No backend required - runs entirely in the browser
  • Easy to host on GitHub Pages

Quick Start

Option 1: Local Development

  1. Clone the repository and navigate to the dashboard directory:

    cd stale-dashboard

  2. Serve the files using a local web server:

    # Using Python 3
python3 -m http.server 8000

# Using Node.js
npx http-server -p 8000

  3. Open your browser to http://localhost:8000

Option 2: GitHub Pages Deployment

Note for Maintainers: GitHub Pages must be configured manually through the repository settings. This requires repository admin access and cannot be automated via script.

  1. Enable GitHub Pages in the repository (typically upstream konveyor/release-tools):

    • Go to repository Settings
    • Navigate to "Pages" section
    • Set source to "Deploy from a branch"
    • Select the main branch
    • Set the folder to / (root)
    • Click "Save"

  2. Access the dashboard at:

    https://konveyor.github.io/release-tools/stale-dashboard/

    Or if deploying from a fork:

    https://YOUR-USERNAME.github.io/release-tools/stale-dashboard/

Configuration

Adding Repositories

Edit config.js to add more repositories as you deploy the stale workflow to them:

repositories: [
    { org: 'konveyor', repo: 'analyzer-lsp' },
    { org: 'konveyor', repo: 'tackle2-hub' },
    { org: 'konveyor', repo: 'tackle2-ui' },
    // Add more repositories here
]

GitHub Token

GitHub's API has rate limits:

  • Unauthenticated: 60 requests per hour
  • Authenticated: 5,000 requests per hour

Token Requirements:

  • Optional: For viewing data (recommended to avoid rate limits)
  • Required: For closing stale items from the dashboard

To create a GitHub Personal Access Token:

  1. Go to https://github.com/settings/tokens
  2. Click "Generate new token" → "Generate new token (classic)"
  3. Give it a descriptive name (e.g., "Stale Dashboard")
  4. Select scopes based on your needs:
    • Read-only access: public_repo (view stale items, avoid rate limits)
    • Close items: repo (full repository access - required to close issues/PRs)
  5. Click "Generate token"
  6. Copy the token

Note: The repo scope grants write access to your repositories. Only use tokens with this scope if you need to close stale items from the dashboard.

Setting the Token

Method 1: Browser Console (Recommended for GitHub Pages)

This method stores your token securely in your browser's local storage without committing it to the repository.

  1. Open the browser developer console:

    • Chrome/Edge: Press F12 or Cmd+Option+J (Mac) / Ctrl+Shift+J (Windows/Linux)
    • Firefox: Press F12 or Cmd+Option+K (Mac) / Ctrl+Shift+K (Windows/Linux)
    • Safari: Enable Developer menu in Preferences → Advanced, then press Cmd+Option+C

  2. Navigate to the Console tab in the developer tools panel

  3. Type the following command in the console and press Enter:

    setGitHubToken('ghp_your_actual_token_here')

    Replace ghp_your_actual_token_here with your actual GitHub personal access token.

  4. You should see:

    GitHub token saved to localStorage
Refresh the page to use the new token

  5. Refresh the page to apply the token. The dashboard will now use your token for API requests.

The token will be stored in localStorage and persist across browser sessions. You won't need to re-enter it unless you clear your browser data or use a different browser/device.

Method 2: Direct Configuration (Not recommended for public repos)

Edit config.js:

githubToken: 'your_token_here',

Important: Never commit your token to a public repository!

To clear the token:

clearGitHubToken()

Troubleshooting Token Setup:

If you see Uncaught ReferenceError: setGitHubToken is not defined:

  1. Make sure the page has fully loaded (wait for the dashboard to appear)
  2. Hard refresh the page: Cmd+Shift+R (Mac) or Ctrl+F5 (Windows/Linux)
  3. Check the browser console for any red JavaScript errors
  4. Verify you're running the command in the Console tab (not Elements or Network)

To verify your token is set:

localStorage.getItem('github_token')

This will display your stored token (or null if not set).

Customizing the Stale Close Message

When closing stale items from the dashboard, a comment is automatically posted before closing. You can customize this message in config.js:

staleCloseMessage: `This issue/PR has been marked as stale and is being closed due to inactivity. If you believe this is still relevant, please feel free to reopen it with updated information or context.

Thank you for your contributions to the Konveyor project!`

The message will be posted as a comment on the issue/PR before it is closed.

Automatic Token Validation

The dashboard automatically checks your GitHub token permissions when it loads:

  • With repo scope: Close buttons are enabled and shown in red
  • Without repo scope: Close buttons are disabled (greyed out) with a tooltip explaining why
  • No token: Close buttons are disabled

Check your browser console for detailed information about token permissions. The dashboard will log:

✓ GitHub token has write access (repo scope)

or

✗ GitHub token does not have write access. Close buttons will be disabled.
  Current scopes: public_repo
  To enable closing items, create a token with "repo" scope.

Dashboard Features

Statistics Cards

  • Total Stale Items: Combined count of stale issues and PRs
  • Stale Issues: Count of stale issues
  • Stale PRs: Count of stale pull requests
  • Repositories: Number of repositories with stale items

Historical Trends (Optional)

If you enable historical data collection, the dashboard displays:

  • Stale Items Over Time: Line chart showing trends in stale issues and PRs
  • Repository Breakdown: Bar chart showing which repos have the most stale items
  • Time Period Selector: View trends for last 30/60/90/180/365 days or all time

To enable historical trends, see Enabling Historical Data Collection below.

Filters

  • Repository: Filter by specific repository
  • Type: Show only issues or only PRs
  • Search: Search by title text
  • Clear Filters: Reset all filters

Table View

  • Sortable columns (click headers to sort)
  • Color-coded badges for issues vs PRs
  • Label display
  • Direct links to GitHub
  • Close Button: Close stale items directly from the dashboard
    • Requires GitHub token with repo scope
    • Buttons are automatically disabled if token lacks write permissions
    • Hover over disabled buttons to see why they're disabled
    • Shows confirmation dialog before closing
    • Posts a configurable closing message as a comment
    • Automatically refreshes the dashboard after closing

Stale Workflow Integration

This dashboard is designed to work with the stale workflow deployed via the stale-workflow tool. The workflow:

  • Marks issues and PRs as stale after 60 days of inactivity
  • Adds the stale label
  • Does not auto-close items
  • Removes the stale label when items are updated

To deploy the stale workflow to a repository:

cd stale-workflow
./deploy-stale-workflow.sh konveyor/repository-name

See the stale-workflow README for more information.

Enabling Historical Data Collection

To track trends over time, automated data collection can be enabled that runs daily and commits snapshots to the repository.

Note: This feature should be enabled in the upstream konveyor/release-tools repository by a maintainer. This ensures everyone views the same historical data on a centralized dashboard.

Setup (for Maintainers)

Prerequisites:

  • Repository admin/write access
  • GitHub CLI installed and authenticated

  1. Run the setup script from the stale-workflow directory:

    cd stale-workflow
./setup-history-collection.sh

    This will automatically create a pull request to add the history collection workflow.

  2. Review and merge the PR.

  3. Important - Manual Configuration Required: After merging, enable workflow write permissions:

    • Go to Settings > Actions > General
    • Under "Workflow permissions", select "Read and write permissions"
    • Click "Save"

    Note: This step cannot be automated and must be done manually by a repository maintainer.

  4. The workflow will run automatically daily at 2:00 AM UTC, or can be triggered manually:

    gh workflow run collect-stale-history.yml

For Non-Maintainers

If you're not a maintainer but want to see historical trends, wait for a maintainer to enable this feature in upstream. Once enabled, the dashboard will automatically display trend charts when you visit it.

How It Works

  • The workflow collects data from all repositories in stale-dashboard/config.js
  • Creates a JSON file with the date (e.g., 2025-11-01.json) in stale-dashboard/data/history/
  • Commits the data automatically
  • The dashboard detects these files and displays trend charts

Data Format

Each historical data file contains:

{
  "date": "2025-11-01",
  "totals": {
    "totalStale": 42,
    "staleIssues": 30,
    "stalePRs": 12,
    "repositories": 5
  },
  "repositories": [...]
}

Browser Support

The dashboard works in all modern browsers:

  • Chrome/Edge (latest)
  • Firefox (latest)
  • Safari (latest)

Troubleshooting

No data showing

  1. Check browser console for errors
  2. Verify repositories are configured correctly in config.js
  3. Ensure the stale workflow is deployed and has run
  4. Check GitHub API rate limits

Rate limit errors

  • Add a GitHub token (see Configuration above)
  • Wait for rate limit to reset (check console for reset time)

CORS errors

  • The GitHub API supports CORS, so this shouldn't happen
  • If using a local file:// URL, use a local web server instead

Close button not working

  • Ensure you have a GitHub token set with repo scope (not just public_repo)
  • Check browser console for error messages
  • Verify you have permissions to close issues in the target repository
  • Make sure you're not hitting API rate limits

Contributing

Contributions are welcome! Please follow the Konveyor community guidelines.

License

See the main repository LICENSE file.