> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawtograder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository Analytics

> Collect and review GitHub activity for student assignment repositories

Repository Analytics pulls activity from each student's assignment repository (commits, pull requests, issues, and comments) and surfaces it in the submission view for instructors and graders. Use it to audit contributions on group work, sanity-check timelines on individual assignments, and link rubric checks to concrete GitHub activity.

Analytics are opt-in per assignment and only visible to staff. The dashboard lives under the **Repo Analytics** tab on any submission page.

## What Gets Collected

For each repository, Pawtograder stores two kinds of records:

* **Items** — individual GitHub events with author, creation date, state, URL, and (where applicable) file-change summaries or labels. Item types are:
  * `commit`
  * `pr` (pull request)
  * `issue`
  * `issue_comment`
  * `pr_review_comment`
* **Daily aggregates** — per-day counts of each item type for the activity chart.

No source code is stored — only the metadata GitHub exposes for each event. When a commit's SHA matches a Pawtograder submission, the items table shows a **View submission** link next to it.

## Enabling Analytics

Analytics are off by default. To turn them on:

1. Open the assignment configuration page (create or edit).
2. Check **Enable repository analytics**.
3. Save.

The assignment must belong to a class with a GitHub organization configured. Only assignments with this flag set are picked up by the daily refresh job and accept manual refresh requests.

## Refreshing Data

Two refresh paths exist:

* **Daily background refresh.** A cron job runs hourly and, during the 2:00 AM UTC hour, enqueues one eligible assignment per minute (staggered to spread GitHub API load). An assignment is eligible if it is released, not archived, has `enable_repo_analytics = true`, and has a due date on or after the current UTC date. Bulk fetches are batched in groups of 20 repositories and dispatched through a low-priority async queue.
* **Manual refresh.** The **Refresh** button on the dashboard calls the `enqueue_repo_analytics_fetch` RPC for the current repository. The fetch status panel shows the last fetched timestamp and the current state (`idle`, `fetching`, `completed`, `error`).

<Note>
  Manual refreshes are rate-limited to **once per 10 minutes per repository**. If you hit the limit, the RPC returns the time at which the next refresh is allowed.
</Note>

## Linking Rubric Checks to KPI Categories

Rubric checks can declare a `kpi_category` that maps the check to one type of GitHub activity. When a check has a KPI category, the rubric sidebar shows a **View \[category]** link that opens the Repo Analytics tab pre-filtered to the matching items.

Valid categories (defined by the `repo_analytics_kpi_category` enum):

| `kpi_category`       | Filters analytics to |
| -------------------- | -------------------- |
| `commits`            | Commits              |
| `prs_opened`         | Pull requests        |
| `pr_review_comments` | PR review comments   |
| `issues_opened`      | Issues               |
| `issues_closed`      | Closed issues        |
| `issue_comments`     | Issue comments       |

For the YAML syntax used to set `kpi_category` on a check, see the [Rubrics reference](/staff/assignments/rubrics).

## Filtering, Expanding, and Exporting

The **Items** view lists every collected event with a type badge, title or commit message, author (mapped to a student profile when possible), date, and state. Expanding a commit or PR row shows the per-file additions/deletions; expanding an issue row shows its labels, assignees, and a body preview.

The **Activity Chart** view shows a stacked daily bar chart across all tracked item types, useful for spotting late starts or pre-deadline crunches.

Use the type filter buttons (or a rubric check's KPI link) to narrow the items table. Click **Export CSV** to download the currently visible items, including type, GitHub ID, title, author, date, state, file-change summary, and GitHub URL.

## Access Control

Repo Analytics is staff-only. The underlying tables (`repository_analytics_daily`, `repository_analytics_items`, `repository_analytics_fetch_status`) restrict reads to graders and instructors of the class via RLS; students cannot see the tab on their own or anyone else's submission.