Frontmatter
| id | 7377 |
| title | Create Script to Sync New GitHub Issues to Local Markdown Files |
| state | Closed |
| labels | enhancementhelp wantedgood first issuehacktoberfestai |
| assignees | nabeel001 |
| createdAt | Oct 5, 2025, 3:10 PM |
| updatedAt | Oct 9, 2025, 8:42 PM |
| githubUrl | https://github.com/neomjs/neo/issues/7377 |
| author | tobiu |
| commentsCount | 5 |
| parentIssue | 7364 |
| subIssues | [] |
| subIssuesCompleted | 0 |
| subIssuesTotal | 0 |
| blockedBy | [] |
| blocking | [] |
| closedAt | Oct 9, 2025, 8:42 PM |
Create Script to Sync New GitHub Issues to Local Markdown Files
Hi @tobiu I would like to contribute to this issue. Kindly assign this to me
Hi, and thanks for your interest.
These tickets require the "ai native" workflows, so you need to read these 2 first: https://github.com/neomjs/neo/blob/dev/.github/WORKING_WITH_AGENTS.md https://github.com/neomjs/neo/blob/dev/.github/AI_QUICK_START.md
Since the epic subs strongly build on and relate to each other, I also strongly recommend to join the Slack and / or Discord Channels, so that you guys can sync. Like a real project :)
https://join.slack.com/t/neomjs/shared_invite/zt-6c50ueeu-3E1~M4T9xkNnb~M_prEEOA https://discord.gg/6p8paPq
More Input from Gemini:
✦ That's a good question. Let's analyze the dependencies for the modified ticket, ticket-sync-gh-issues-to-local.md.
A contributor working on this ticket would need to perform these main tasks:
- Refactor the existing createGhIssue.mjs script to extract utility functions.
- Use the gh issue list command to fetch all remote issues.
- Use the gh issue view command to get the content of specific issues.
- Write new local markdown files using the refactored utility functions.
Blocker Analysis
The situation is identical to the PR we just reviewed:
Code Dependency: There are no code blockers. The createGhIssue.mjs script that needs to be refactored is already merged into the repository.
Environment Dependency: The script's core functionality relies entirely on making authenticated calls to the GitHub API via the gh CLI. This means the developer's environment must be authenticated.
The task of documenting how to set up this authentication is ticket-setup-github-cli-authentication.md, which is a Phase 1 ticket and is not yet complete.
Conclusion
Formally, yes, it is blocked. According to the phases we've defined, the authentication setup guide is a prerequisite. We cannot require someone to work on this task without having provided them with the instructions on how to set up their environment.
Practically, it is available for a proactive contributor. Just like the contributor who submitted the first PR, a new contributor could decide to install and authenticate the GitHub CLI on their own without waiting for our guide.
Recommendation: We can leave the ticket as is. It's ready for an enterprising contributor who is comfortable with the GitHub CLI, but we should not expect the work to begin until the Phase 1 authentication ticket is complete.
hey @tobiu i believe this is almost exactly the same as #7368 or are there some other goals with this?
there is a similarity, but a different use case: we will need the create script, when contributors use agents to create new tickets. however, "normal users" can create tickets directly on GitHub. E.g., if they discover a bug inside the neo website or examples. so we will frequently need to sync GH issues back into our internal md files.
the benefit of the md files: we drop them into chromaDB (the ai knowledge base), so gemini can use it to query for tickets based on vector distances more easily.
Hi @tobiu I have created the script to sync new gitHub issues to local markdown files. Kindly verify and merge the PR.
While our primary workflow will be local-first, any contributor can still create an issue directly on GitHub. To ensure our local
.github/ISSUE/directory remains a comprehensive source of truth, we need a script to find any GitHub issues that are missing a corresponding local markdown file and create one for them. This script will be run periodically to keep the two systems in sync.To ensure consistency, this script should reuse the file-writing and formatting logic from the existing
buildScripts/ai/createGhIssue.mjsscript. This will likely require refactoring shared utility functions into a common module.Acceptance Criteria
createGhIssue.mjs(such as for filename generation and metadata prepending) are refactored into a shared utility module (e.g.,buildScripts/ai/util/ticketUtils.mjs).buildScripts/ai/syncGhIssuesToLocal.mjs).gh issue listto get a list of all non-closed issues..github/ISSUE/*.mdand parsing theGH ticket idfrom each).gh issue view <ID>to get the title and body..github/ISSUE/gh-<ID>-<title>.md) using the refactored utility functions to ensure consistent formatting.