id: good-first-issue-scout
namespace: company.team
description: |
Scout open GitHub "good first issue" / "help wanted" issues, score each one
by competition (assignees, comments, recency), and post the most promising
opportunities to Slack every 12 hours.
triggers:
- id: every_12_hours
type: io.kestra.plugin.core.trigger.Schedule
description: Run the scout twice a day so contributors see fresh opportunities.
cron: "0 */12 * * *"
inputs:
- id: repository
type: STRING
displayName: GitHub Repository
description: Target repository in 'owner/repo' format (e.g. kestra-io/kestra).
defaults: kestra-io/kestra
- id: labels
type: STRING
displayName: Issue Labels
description: Comma-separated labels to search for (e.g. "good first issue,help wanted").
defaults: "good first issue,help wanted"
- id: max_issues
type: INT
displayName: Maximum Issues
description: Maximum issues to fetch from the GitHub Search API per run (1-100).
defaults: 30
- id: max_age_days
type: INT
displayName: Maximum Issue Age (Days)
description: Ignore issues created more than this many days ago.
defaults: 180
- id: top_n
type: INT
displayName: Top Opportunities To Notify
description: How many of the best-scoring issues to include in the notification.
defaults: 5
- id: notify_slack
type: BOOL
displayName: Notify Slack
description: Send the digest to Slack when new opportunities are found.
defaults: true
tasks:
- id: load_seen
type: io.kestra.plugin.core.kv.Get
description: Load previously notified issue URLs so we avoid duplicate notifications.
key: "good-first-issue-scout-seen"
errorOnMissing: false
- id: search_and_score
type: io.kestra.plugin.scripts.python.Script
description: Search GitHub issues, enrich with commenters/assignees, score
competition, and rank.
containerImage: python:3.11-slim
env:
GITHUB_TOKEN: "{{ secret('GITHUB_TOKEN') }}"
inputFiles:
seen.json: "{{ outputs.load_seen.value | toJson }}"
script: |
import json, os, time, urllib.request, urllib.parse
from datetime import datetime, timezone
from kestra import Kestra
logger = Kestra.logger()
TOKEN = os.environ.get("GITHUB_TOKEN", "")
REPO = """{{ inputs.repository }}"""
LABELS = [l.strip() for l in """{{ inputs.labels }}""".split(",") if l.strip()]
MAX_ISSUES = min(max(int("{{ inputs.max_issues }}"), 1), 100)
MAX_AGE = int("{{ inputs.max_age_days }}")
TOP_N = int("{{ inputs.top_n }}")
def gh_get(url):
headers = {"Accept": "application/vnd.github+json", "User-Agent": "Kestra-Good-First-Issue-Scout"}
if TOKEN:
headers["Authorization"] = f"Bearer {TOKEN}"
for attempt in range(3):
req = urllib.request.Request(url, headers=headers)
try:
with urllib.request.urlopen(req, timeout=30) as r:
return json.loads(r.read().decode()), dict(r.headers)
except Exception as e:
status = getattr(e, "code", None)
logger.warning(f"GET {url} attempt {attempt+1} failed: {e}")
if status == 403: # likely rate limit
time.sleep(2 ** attempt * 5)
elif status in (429,) or (status and status >= 500):
time.sleep(2 ** attempt * 2)
else:
break
return None, {}
# 1. Build search query: repo + labels + open issues only.
label_q = " ".join(f'label:"{l}"' for l in LABELS)
q = f"repo:{REPO} {label_q} type:issue state:open"
search_url = "https://api.github.com/search/issues?q=" + urllib.parse.quote(q) + f"&per_page={MAX_ISSUES}&sort=updated&order=desc"
logger.info(f"Searching: {q}")
data, _ = gh_get(search_url)
items = (data or {}).get("items", []) if isinstance(data, dict) else []
logger.info(f"Search returned {len(items)} items")
try:
with open("seen.json") as f:
seen_raw = f.read().strip()
parsed = json.loads(seen_raw) if seen_raw else []
seen = set(parsed) if isinstance(parsed, list) else set()
except Exception:
seen = set()
now = datetime.now(timezone.utc)
scored = []
for it in items:
try:
number = it.get("number")
repo_url = (it.get("repository_url") or "")
repo = repo_url.replace("https://api.github.com/repos/", "") or REPO
created = it.get("created_at", "")
updated = it.get("updated_at", "")
created_dt = datetime.fromisoformat(created.replace("Z", "+00:00"))
age_days = (now - created_dt).days
if age_days > MAX_AGE:
continue
assignees = it.get("assignees") or []
assignee_names = [a.get("login", "unknown") for a in assignees if isinstance(a, dict)]
n_comments = int(it.get("comments") or 0)
# 2. Fetch commenters (gracefully handle 0 comments / deleted users).
commenters = set()
if n_comments > 0 and number:
curl = f"https://api.github.com/repos/{repo}/issues/{number}/comments?per_page=100"
cdata, _ = gh_get(curl)
if isinstance(cdata, list):
for c in cdata:
u = (c.get("user") or {})
if u and u.get("login"):
commenters.add(u["login"])
# deleted users have user: null -> skipped
n_commenters = len(commenters)
# 3. Competition score: assignees weigh heaviest, then discussion volume.
if len(assignee_names) == 0 and n_comments <= 2:
level, emoji = "Low", "🟢"
elif len(assignee_names) == 0 and n_comments <= 6:
level, emoji = "Medium", "🟡"
elif len(assignee_names) >= 1 or n_comments > 10:
level, emoji = "High", "🔴"
else:
level, emoji = "Medium", "🟡"
scored.append({
"title": it.get("title", "(no title)"),
"repository": repo,
"url": it.get("html_url", ""),
"labels": [l.get("name") for l in (it.get("labels") or []) if isinstance(l, dict)],
"created_at": created, "updated_at": updated,
"comments": n_comments, "assignees": len(assignee_names),
"assignee_names": assignee_names,
"commenters": n_commenters, "commenter_names": sorted(commenters),
"age_days": age_days, "competition": level, "emoji": emoji,
"is_new": it.get("html_url", "") not in seen,
"_rank": (0 if level == "Low" else 1 if level == "Medium" else 2, len(assignee_names), n_comments, age_days),
})
except Exception as e:
logger.warning(f"Skipping issue due to parse error: {e}")
continue
scored.sort(key=lambda s: s["_rank"])
for s in scored:
s.pop("_rank", None)
top = scored[:TOP_N]
fresh_top = [s for s in top if s["is_new"]]
Kestra.outputs({"total": len(scored), "top": top, "fresh": fresh_top,
"seen": sorted(seen | {s["url"] for s in fresh_top}),
"slack_text": "\n\n".join(
f"{s['emoji']} *<{s['url']}|{s['title']}>*\n`{s['repository']}`, comments: {s['comments']}, assignees: {s['assignees']}, commenters: {s['commenters']}, age: {s['age_days']}d, competition: {s['competition']}"
for s in fresh_top).replace('"', "'") or "No new opportunities since last run."})
- id: maybe_notify
type: io.kestra.plugin.core.flow.If
description: Post to Slack only when there are fresh opportunities and
notifications are enabled.
condition: "{{ inputs.notify_slack and (outputs.search_and_score.vars.fresh |
length) > 0 }}"
then:
- id: notify_slack
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Deliver the ranked Good First Issue digest to Slack.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "🟢 Good First Issue opportunities in {{ inputs.repository }}",
"blocks": [
{"type": "header", "text": {"type": "plain_text", "text": "🟢 Good First Issue Scout, {{ inputs.repository }}"}},
{"type": "section", "text": {"type": "mrkdwn", "text": "{{ outputs.search_and_score.vars.slack_text }}"}},
{"type": "context", "elements": [{"type": "mrkdwn", "text": "Labels: {{ inputs.labels }} | Execution: {{ execution.id }} | 🟢 Low = appears unassigned + quiet (not a guarantee, check the thread before starting work)"}}]}
]
}
else:
- id: log_noop
type: io.kestra.plugin.core.log.Log
description: Log when there is nothing new to report.
message: "Scout found {{ outputs.search_and_score.vars.total }} scored issues,
{{ outputs.search_and_score.vars.fresh | length }} fresh. Nothing to
notify."
- id: save_seen
type: io.kestra.plugin.core.kv.Set
description: Persist notified issue URLs so the next run only alerts on new
opportunities.
key: "good-first-issue-scout-seen"
kvType: JSON
value: "{{ outputs.search_and_score.vars.seen }}"
errors:
- id: alert_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Alert Slack if the scout itself fails (API outage, bad token, rate limit).
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "🚨 Good First Issue Scout failed for {{ inputs.repository }} in execution {{ execution.id }}. Check GITHUB_TOKEN / rate limits."
}
outputs:
- id: total_scored
type: INT
value: "{{ outputs.search_and_score.vars.total }}"
- id: top_opportunities
type: STRING
value: "{{ outputs.search_and_score.vars.top | toJson }}"