GitHub Actions → Pony Migration Analysis

[SeanTAllen]

Assessment of what github_rest_api would need to replace the Python code in
each ponylang GitHub Action bot. All four bots currently use Python + PyGithub.

Quick Summary

Action	GitHub API complexity	Git operations	Porting difficulty
release-notes-reminder-bot-action	Low (5 endpoints)	None	Easiest
changelog-bot-action	Medium (4 endpoints)	Clone, commit, push	Hard (git)
release-notes-bot-action	Medium (5 endpoints)	Clone, commit, push	Hard (git)
release-bot-action	Medium (4 endpoints)	Tag, push, delete tag	Hard (git + Zulip)

---

release-notes-reminder-bot-action

What it does: When a changelog label is added to a PR, checks if release
notes are included. If not, posts a reminder comment. Uses a sentinel HTML
comment (<!-- release-note-reminder-bot -->) to avoid duplicate reminders.

GitHub API operations needed:

Operation	Endpoint	github_rest_api status
Get repository	GET /repos/{owner}/{repo}	GetRepository — exists
Get issue (PR as issue)	GET /repos/{owner}/{repo}/issues/{number}	GetIssue — exists
List issue comments	GET /repos/{owner}/{repo}/issues/{number}/comments	GetIssueComments — exists (but not paginated; may be sufficient for checking sentinel)
Get PR files	GET /repos/{owner}/{repo}/pulls/{number}/files	GetPullRequestFiles — exists (but not paginated; only returns filename field)
Create issue comment	POST /repos/{owner}/{repo}/issues/{number}/comments	CreateIssueComment — exists

What's missing for the API:

• PullRequestFile model is very sparse (only filename). The bot checks for
  files with status == "added" in the .release-notes/ directory. Need to add
  status field to PullRequestFile. (CommitFile already has status — same
  pattern.)
• GetIssueComments may need pagination if PRs have many comments, but for
  checking a sentinel this is likely fine iterating the first page.

Git operations: None.

Other dependencies: None.

Assessment: This is the most portable action. All 5 API endpoints already
exist in the library. The only gap is the status field on PullRequestFile.
No git operations, no external services.

Missing from github_rest_api:

1. PullRequestFile needs status field

---

changelog-bot-action

What it does: When a PR is merged, searches for the PR by commit SHA, checks
for changelog labels, then updates CHANGELOG.md using changelog-tool and
pushes the change.

GitHub API operations needed:

Operation	Endpoint	github_rest_api status
Search issues by SHA	GET /search/issues?q=is:merged+sha:{sha}+repo:{repo}	SearchIssues — exists (not paginated, but only needs first result)
Get repository	GET /repos/{owner}/{repo}	GetRepository — exists
Get pull request	GET /repos/{owner}/{repo}/pulls/{number}	GetPullRequest — exists
PR labels	(part of PR response)	PullRequest model has labels field — exists
PR title, html_url, base branch	(part of PR response)	PullRequest model has these — exists

What's missing for the API: Nothing significant. SearchIssues works for the
query pattern used. All needed PR fields are already modeled.

Git operations (problematic for Pony port):

• Clone repository via HTTPS with embedded credentials
• Configure git user name/email
• git add CHANGELOG.md
• git commit -m "Update CHANGELOG for PR #N"
• git push with retry logic (pull --rebase on conflict, up to 5 attempts)

Other dependencies:

• changelog-tool CLI (already a Pony binary — could be used as a library or
  kept as a subprocess call)

Assessment: The GitHub API side is fully covered. The blocker is git
operations — Pony has no git library. The bot needs to clone, commit, and push,
with retry/rebase logic on push conflicts. This would require either:

• Shelling out to git via Pony's process package
• A Pony git library (doesn't exist)
• Keeping Python for git operations and only using github_rest_api for the API parts (defeats the purpose)

Missing from github_rest_api:

1. Nothing for the API portion

---

release-notes-bot-action

What it does: When a PR is merged, searches for the PR by commit SHA, checks
each commit for .release-notes/ file changes, then either merges them into
next-release.md (if PR has changelog label) or deletes them (if no label).

GitHub API operations needed:

Operation	Endpoint	github_rest_api status
Search issues by SHA	GET /search/issues?q=is:merged+sha:{sha}+repo:{repo}	SearchIssues — exists
Get repository	GET /repos/{owner}/{repo}	GetRepository — exists
Get commit	GET /repos/{owner}/{repo}/commits/{sha}	GetCommit — exists
Commit files	(part of commit response)	CommitFile model has sha, status, filename — exists
Get pull request	GET /repos/{owner}/{repo}/pulls/{number}	GetPullRequest — exists
PR labels	(part of PR response)	PullRequest model has labels — exists

What's missing for the API: Nothing. All endpoints and fields needed are
already present.

Git operations (problematic for Pony port):

• Clone repository via HTTPS with embedded credentials
• Configure git user name/email
• git rm (remove release notes files)
• git add .release-notes/next-release.md
• git commit
• git push with retry logic (pull --rebase on conflict, up to 5 attempts)

Other dependencies: None beyond git.

Assessment: Same situation as changelog-bot-action. API side is covered.
Git operations are the blocker.

Missing from github_rest_api:

1. Nothing for the API portion

---

release-bot-action

What it does: Orchestrates the entire release process for ponylang projects
via a 3-phase tag-triggered workflow (prepare → release artifacts → announce).
Contains 15 individual scripts.

GitHub API operations needed:

Operation	Endpoint	github_rest_api status
Get repository	GET /repos/{owner}/{repo}	GetRepository — exists
List issues with label	GET /repos/{owner}/{repo}/issues?labels={label}	missing — need GetRepositoryIssues (paginated, with label filter)
Create issue comment	POST /repos/{owner}/{repo}/issues/{number}/comments	CreateIssueComment — exists
Get release by tag	GET /repos/{owner}/{repo}/releases/tags/{tag}	missing — need GetReleaseByTag
Update release	PATCH /repos/{owner}/{repo}/releases/{id}	missing — need UpdateRelease (requires HTTP PATCH support)
Create release	POST /repos/{owner}/{repo}/releases	CreateRelease — exists

What's missing for the API:

1. GetRepositoryIssues with label filter (paginated) — used to find "Last
   Week in Pony" issue on ponylang-website
2. GetReleaseByTag — get a release by its tag name
3. UpdateRelease (PATCH) — update an existing release's notes. Requires adding
   HTTP PATCH support to the request infrastructure.

Git operations (extensive, problematic for Pony port):

• Configure git user name/email
• git add, git commit, git push (with retry/rebase) — in 8 of 15 scripts
• git tag -a (create annotated tags)
• git push origin <tag> (push tags)
• git push --delete origin <tag> (delete remote tags)

Other dependencies:

• changelog-tool CLI (Pony binary, used via subprocess)
• Zulip API (Python zulip library — sends release announcements)
• File manipulation: reads/writes CHANGELOG.md, VERSION, corral.json, action.yml,
  README.md with regex substitutions, .release-notes/ rotation

Assessment: This is the hardest to port. It has the most git operations
(tagging, pushing, deleting remote tags), needs HTTP PATCH for the GitHub API,
interacts with Zulip, and does complex file manipulation. The 15 scripts form
a multi-phase workflow with inter-dependencies via tag triggers. Even if the
API side were complete, the git and Zulip dependencies make a full port
impractical without a Pony git library and Zulip client.

Missing from github_rest_api:

1. GetRepositoryIssues with label filter (paginated)
2. GetReleaseByTag
3. UpdateRelease (requires HTTP PATCH infrastructure)

---

Cross-cutting concerns for all git-dependent actions

All three git-dependent actions (changelog-bot, release-notes-bot, release-bot)
share these patterns that Pony currently can't handle natively:

1. Git clone with HTTPS credentials — embeds {actor}:{token}@github.com
   in clone URL
2. Git config — sets user.name, user.email, autosetuprebase, safe.directory
3. Push with retry/rebase — up to 5 attempts, pulling with rebase between
   retries to handle concurrent pushes
4. Subprocess execution — calls changelog-tool CLI

Pony's process package could shell out to git and changelog-tool, but
the retry/rebase logic and error handling would be more complex than in Python.
The absence of a Pony git library is the primary blocker for porting these
actions.

Recommended porting order (if pursued)

1. release-notes-reminder-bot-action — Only needs PullRequestFile.status
   field added. No git, no external services. Could be ported today.
2. pony-sync-helper improvements — Already Pony, needs list org repos +
   list issues with label filter (see NEEDED_TO_SERVE_SYNC_HELPER.md).
3. changelog-bot-action / release-notes-bot-action — API side is ready.
   Blocked on git operations.
4. release-bot-action — Most complex. Needs API additions + git + Zulip.