feat: implement automated issue claiming, assignment limits, and stale assignment cleanup via GitHub Actions

Author: JhaSourav07

.github/scripts/issue-management/assign-handler.js

@@ -35,7 +35,7 @@ async function handleAssign({ github, context, username, hasWriteAccess }) {
       owner,
       repo,
       issue_number: issueNumber,
-      body: `❌ Cannot assign \`@${username}\` — this issue is already **closed**.`,
+      body: `❌ Commands cannot be used on closed issues.`,
     });
     return;
   }

.github/scripts/issue-management/claim-handler.js

@@ -0,0 +1,81 @@
+async function findExistingAssignment(github, owner, repo, username, currentIssueNumber) {
+  const { data: issues } = await github.rest.issues.listForRepo({
+    owner,
+    repo,
+    assignee: username,
+    state: 'open',
+    per_page: 100,
+  });
+
+  const assignedIssues = issues.filter(
+    (issue) => !issue.pull_request && issue.number !== currentIssueNumber
+  );
+
+  return assignedIssues.length > 0 ? assignedIssues[0] : null;
+}
+
+async function handleClaim({ github, context }) {
+  const { owner, repo } = context.repo;
+  const issueNumber = context.payload.issue.number;
+  const issueState = context.payload.issue.state;
+  const commenter = context.payload.comment.user.login;
+
+  if (issueState === 'closed') {
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: issueNumber,
+      body: `❌ Commands cannot be used on closed issues.`,
+    });
+    return;
+  }
+
+  const currentAssignees = context.payload.issue.assignees.map((a) => a.login.toLowerCase());
+
+  if (currentAssignees.length > 0) {
+    if (currentAssignees.includes(commenter.toLowerCase())) {
+      await github.rest.issues.createComment({
+        owner,
+        repo,
+        issue_number: issueNumber,
+        body: `ℹ️ You are already assigned to this issue.`,
+      });
+      return;
+    }
+    const assigneeList = currentAssignees.map((a) => `@${a}`).join(', ');
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: issueNumber,
+      body: `❌ This issue is already assigned to ${assigneeList}`,
+    });
+    return;
+  }
+
+  const existingIssue = await findExistingAssignment(github, owner, repo, commenter, issueNumber);
+  if (existingIssue) {
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: issueNumber,
+      body: `❌ You already have an active assigned issue.\nPlease complete or unassign your current issue first.\n\n> 📋 Active issue: [#${existingIssue.number} — ${existingIssue.title}](${existingIssue.html_url})`,
+    });
+    return;
+  }
+
+  await github.rest.issues.addAssignees({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    assignees: [commenter],
+  });
+
+  await github.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    body: `✅ Successfully assigned issue to @${commenter}\n\n> 💡 Please read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md) if you haven't already. Good luck! 🚀`,
+  });
+}
+
+module.exports = { handleClaim };

.github/scripts/issue-management/main.js

@@ -3,6 +3,7 @@ const { hasWriteAccess } = require('./permissions');
 const { handleAssign } = require('./assign-handler');
 const { handleUnassign } = require('./unassign-handler');
 const { handleAddLabel } = require('./addlabel-handler');
+const { handleClaim } = require('./claim-handler');
 
 module.exports = async ({ github, context, core }) => {
   const commentBody = context.payload.comment?.body;
@@ -44,6 +45,9 @@ module.exports = async ({ github, context, core }) => {
       case 'addlabel':
         await handleAddLabel({ github, context, labelArgs: parsed.labels });
         break;
+      case 'claim':
+        await handleClaim({ github, context });
+        break;
     }
   } catch (error) {
     core.error(`Error processing command /${parsed.command}: ${error.message}`);

.github/scripts/issue-management/parse-command.js

@@ -12,6 +12,9 @@ function parseCommand(commentBody) {
     const unassignMatch = line.match(/^\/unassign\s+@([^\s]+)\s*$/i);
     if (unassignMatch) return { command: 'unassign', username: unassignMatch[1] };
 
+    const claimMatch = line.match(/^\/claim\s*$/i);
+    if (claimMatch) return { command: 'claim' };
+
     const addlabelMatch = line.match(/^\/addlabel\s+(.+)$/i);
     if (addlabelMatch) {
       const labels = parseLabels(addlabelMatch[1]);

.github/scripts/issue-management/stale-assignment.js

@@ -0,0 +1,65 @@
+async function handleStaleAssignments({ github, context, core }) {
+  const { owner, repo } = context.repo;
+  const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
+  const now = new Date();
+
+  console.log(`Starting stale assignment check for ${owner}/${repo}`);
+
+  let page = 1;
+  let staleCount = 0;
+
+  while (true) {
+    const { data: issues } = await github.rest.issues.listForRepo({
+      owner,
+      repo,
+      state: 'open',
+      assignee: '*', // Only fetch issues that have at least one assignee
+      per_page: 100,
+      page,
+    });
+
+    if (issues.length === 0) break;
+
+    for (const issue of issues) {
+      // GitHub API returns PRs as issues, we only want actual issues
+      if (issue.pull_request) continue;
+
+      const updatedAt = new Date(issue.updated_at);
+      const timeSinceUpdate = now.getTime() - updatedAt.getTime();
+
+      if (timeSinceUpdate > THREE_DAYS_MS) {
+        console.log(
+          `Issue #${issue.number} has been inactive since ${issue.updated_at}. Removing assignees.`
+        );
+
+        // 1. Remove all assignees
+        const currentAssignees = issue.assignees.map((a) => a.login);
+        if (currentAssignees.length > 0) {
+          await github.rest.issues.removeAssignees({
+            owner,
+            repo,
+            issue_number: issue.number,
+            assignees: currentAssignees,
+          });
+
+          // 2. Post a comment
+          await github.rest.issues.createComment({
+            owner,
+            repo,
+            issue_number: issue.number,
+            body: `⚠️ Assignment automatically removed due to inactivity.\nFeel free to reclaim the issue if you want to continue working on it.`,
+          });
+
+          staleCount++;
+        }
+      }
+    }
+
+    if (issues.length < 100) break;
+    page++;
+  }
+
+  console.log(`Finished checking. Removed assignments from ${staleCount} stale issues.`);
+}
+
+module.exports = handleStaleAssignments;

.github/scripts/issue-management/unassign-handler.js

@@ -2,6 +2,17 @@ async function handleUnassign({ github, context, username, hasWriteAccess }) {
   const { owner, repo } = context.repo;
   const issueNumber = context.payload.issue.number;
   const commenter = context.payload.comment.user.login;
+  const issueState = context.payload.issue.state;
+
+  if (issueState === 'closed') {
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: issueNumber,
+      body: `❌ Commands cannot be used on closed issues.`,
+    });
+    return;
+  }
 
   if (!hasWriteAccess) {
     await github.rest.issues.createComment({

.github/workflows/issue-management.yml

@@ -21,7 +21,8 @@ jobs:
       (
         contains(github.event.comment.body, '/assign') ||
         contains(github.event.comment.body, '/unassign') ||
-        contains(github.event.comment.body, '/addlabel')
+        contains(github.event.comment.body, '/addlabel') ||
+        contains(github.event.comment.body, '/claim')
       )
     steps:
       - name: Checkout Repository

.github/workflows/stale-assignments.yml

@@ -0,0 +1,29 @@
+name: Stale Assignment Expiry
+
+on:
+  schedule:
+    - cron: '0 0 * * *' # Runs daily at midnight UTC
+  workflow_dispatch: # Allows manual triggering from the Actions tab
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  remove-stale-assignments:
+    name: Remove Stale Assignments
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+
+      - name: Process Stale Assignments
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const script = require('./.github/scripts/issue-management/stale-assignment.js');
+            await script({ github, context, core });

CONTRIBUTING.md

@@ -10,6 +10,7 @@
 - [The Standard We Hold](#-the-standard-we-hold)
 - [Local Setup](#-local-setup)
 - [What to Contribute](#-what-to-contribute)
+- [Automated Issue Management & Claiming](#-automated-issue-management--claiming)
 - [Branch & Commit Conventions](#-branch--commit-conventions)
 - [Opening a Pull Request](#-opening-a-pull-request)
 - [Code Style & Quality Gates](#-code-style--quality-gates)
@@ -144,12 +145,56 @@ The accuracy engine lives in `utils/time.ts` and `lib/calculate.ts`.
 
 **Rules for logic changes:**
 
-- All changes must be backward-compatible (no breaking the default behavior)
+- All logic changes must be backward-compatible (no breaking the default behavior)
 - Include a code comment explaining _why_ the logic works, not just _what_ it does
 - If you add a new URL parameter, document it in `README.md`'s parameter table
 
 ---
 
+## 🤖 Automated Issue Management & Claiming
+
+CommitPulse uses a custom, lightweight **GitHub Actions** automation system to manage issues fairly. This ensures that everyone (especially during events like **GSSoC**) gets a chance to contribute and prevents "issue hoarding".
+
+> [!IMPORTANT]
+> **The Golden Rule:** You can only be assigned to **ONE** open issue at a time. Finish it or unassign yourself before claiming another.
+
+### 🎮 Available Commands
+
+Our automation runs entirely through issue comments. Here is how you interact with it:
+
+| Command | Who Can Use It? | What It Does |
+|---------|-----------------|--------------|
+| `/claim` | **Anyone** | Self-assigns the issue to you. |
+| `/addlabel <label1> <label2>` | **Anyone** | Adds labels to the issue (e.g. `/addlabel frontend bug`). |
+| `/unassign @username` | **Maintainers Only** | Removes the assignee from an issue. |
+| `/assign @username` | **Maintainers Only** | Manually assigns someone to an issue. |
+
+### ⏳ The Inactivity Policy (Assignment Expiry)
+
+To keep the project moving, assignments are not permanent.
+- **The 3-Day Rule:** If an issue has an assignee but sees **no activity for 3 days**, our automated background job will remove the assignment.
+- **What counts as activity?** Posting a comment, opening a linked PR, or a maintainer adding a label.
+- **Why?** It frees up stale issues so other active contributors can pick them up. If your issue expires, you can always `/claim` it again if it's still available!
+
+### 💡 GSSoC Contributor Flow
+1. Find an unassigned open issue you want to work on.
+2. Comment `/claim` to lock it in.
+3. Need labels? Comment `/addlabel good-first-issue` (labels must already exist in the repo).
+4. Work on your code and submit a PR within 3 days to avoid expiry.
+5. Once your PR is merged and the issue is closed, you can `/claim` your next one!
+
+### 🆘 Troubleshooting & Edge Cases
+
+If the bot rejects your command, check these common scenarios:
+
+- **"Commands cannot be used on closed issues"**: You cannot claim, assign, or unassign on closed issues. Find an open one!
+- **"You already have an active assigned issue"**: You must finish your current task. If you're stuck, ask a maintainer to `/unassign` you from the old one.
+- **"This issue is already assigned to @username"**: Be faster next time! Look for issues without assignees.
+- **"The following label(s) do not exist"**: You can only add existing repo labels. The bot will reply with a list of valid labels you can use.
+- **"You don't have permission"**: You tried to use `/assign` or `/unassign`. Please use `/claim` instead.
+
+---
+
 ## 🌿 Branch & Commit Conventions
 
 ### Branch Naming

README.md

@@ -234,6 +234,20 @@ Set the `GITHUB_PAT` environment variable in your Vercel project settings, and y
 
 ---
 
+## 🤖 Automated Contributor Workflow
+
+CommitPulse features a fully custom, GitHub Actions-powered **Issue Management System** designed for large open-source events like GSSoC. 
+
+We built an anti-hoarding, self-service automation layer right into the repository:
+- **Self-Claiming:** Contributors can grab issues instantly by commenting `/claim`.
+- **Fair Play:** A strict one-active-issue-per-contributor rule prevents issue hoarding.
+- **Stale Expiry:** A scheduled chron job automatically unassigns inactive contributors after 3 days.
+- **Self-Service Labels:** Anyone can tag issues using `/addlabel <tag>`.
+
+This ensures maintainers aren't bottlenecks and the community moves incredibly fast.
+
+---
+
 ## 🤝 Contributing
 
 CommitPulse is an open project built for the Web3 and open-source community. Whether you want to design a new theme, refine the isometric geometry, or improve timezone edge cases — you are welcome here.