GitHub Projects Markdown Sync

Sync GitHub Projects V2 with Markdown stories. Licensed under the MIT License.

Overview

The latest release introduces a safer, clearer sync model:

• Single entry for md→project with create-only enforcement
• Separated formats: Multi-Story for import, Single-Story for export
• Dry-run diagnostics for CI and previewing plans

This tool synchronises Markdown documents and GitHub Projects (V2) so teams can manage work in text while keeping the project board current.

Requirements

• Node.js 18 or newer

Features

• Create-only import: Multi-Story Markdown → GitHub Project items by Story ID
• Read-only export: GitHub Project → Single-Story Markdown files
• Status mapping: Backlog, Ready, In progress, In review, Done (with aliases)
• Deterministic, idempotent behaviour keyed by Story ID
• Dry-run with structured logs for CI gates
• TypeScript API and runnable examples

Quick start

1. Install the package in a Node.js workspace:

npm install github-projects-md-sync

2. Create a .env file in the project root with credentials that can access GitHub Projects V2:

GITHUB_TOKEN=your_github_tokenPROJECT_ID=your_project_id

3. Run the CLI commands or consume the TypeScript API as described below.

Usage

CLI

Command	Purpose	Key options
npm run md -- <path>	Import Multi-Story Markdown into a project (create-only)	--dry-run to print the plan without calling the API
npm run project [-- <Story-ID>] [<outputDir>]	Export all stories or a single story into Markdown files	Positional Story-ID selects a single story, positional outputDir overrides the destination
npm run project:story -- [Story-ID] [outputDir]	Convenience wrapper for single-story export	Accepts Story-ID and outputDir as positional args or via --story, --output
npx ts-node src/project-to-stories.ts [Story-ID] [outputDir]	Low-level script that powers the exports	Requires PROJECT_ID and GITHUB_TOKEN env vars; positional arguments follow the same rules

• Import Multi-Story Markdown to a GitHub Project (create-only):

npm run md -- stories/test-multi-stories-0.1.11.md

• Optional dry-run plan: simulates the sync and prints the intended GitHub mutations without executing API writes:

npm run md -- stories/test-multi-stories-0.1.11.md --dry-run

• Export GitHub Project items to Single-Story Markdown files:

npm run project
npm run project -- <Story-ID>

As a Library

import{mdToProject,projectToMdWithOptions,projectToMdSingleStory}from"github-projects-md-sync";constprojectId=process.env.PROJECT_ID!;constgithubToken=process.env.GITHUB_TOKEN!;constmdResult=awaitmdToProject(projectId,githubToken,"./markdown-files");constexportAllResult=awaitprojectToMdWithOptions({
projectId,
githubToken,outputPath: "./output-dir",logLevel: "info"});constexportSingleResult=awaitprojectToMdSingleStory(projectId,githubToken,"Story-1234","./single-story");mdResult.logs.forEach((entry)=>{console.log(`[${entry.level.toUpperCase()}] ${entry.message}`, ...entry.args);});if(!mdResult.result.success){console.error("Import run failed",mdResult.result.errors);}if(exportAllResult.result.success){console.log(`Exported ${exportAllResult.result.files.length} files to ${exportAllResult.result.outputDir}`);}else{console.error("Bulk export failed",exportAllResult.result.errors);}if(!exportSingleResult.result.success){console.error("Single story export failed",exportSingleResult.result.errors);}

Examples

The examples/ workspace demonstrates end-to-end usage with ready-made scripts:

• examples/md-to-project.ts — imports markdown from examples/md/ into a project.
• examples/project-to-md.ts — exports project items into examples/items/.
• examples/tests/ — Mocha scenarios that validate the flows.

Sample package.json scripts (from examples/package.json):

{
"scripts": {
"md": "ts-node ./md-to-project.ts",
"project": "ts-node ./project-to-md.ts",
"project:story": "ts-node ./project-to-md.ts --story"
}
}

Run them from the examples/ directory once .env is configured:

npm run md # imports multi-story markdown from examples/md/
npm run project # exports all stories to examples/items/
npm run project:story # exports a single story, prompting when IDs are missing

Using project:story

npm run project:story -- Story-1234

• Prompts for GitHub token and project ID if env vars GITHUB_TOKEN and PROJECT_ID are not set
• Generates markdown for the specified story ID under stories/ by default
• Accepts Story-XXXX via positional arg or --story Story-XXXX
• Overrides the output directory via positional path or --output ./custom-dir

Parameter rules:

• Story-ID positional detection checks for values that match /^Story-/i. If omitted, all stories are exported.
• The first remaining positional argument is treated as the output directory. Without it, files are written to ./stories.
• Flags --story=value / --output=value are equivalent to their spaced counterparts.

Examples:

npm run project -- Story-0456
npm run project ./stories/out-story -- Story-0112
npm run project:story -- Story-0112 ./stories/single
npm run project:story -- --story Story-0112 --output ./stories/single

How to get PROJECT_ID (personal GitHub user)

• Create a new issue in your repository first
• Then go to Projects settings -> Manage access, your GitHub username should appear with Admin role

PowerShell to query PROJECT_ID:

$owner="your_github_username"$repo="your_repo_name"$token="your_github_token_with_repo_and_projects_access"$headers=@{
Authorization="Bearer $token""User-Agent"="PowerShell"Accept="application/json"
}
$query=@"{ repository(owner: "$owner", name: "$repo") { projectsV2(first: 10) { nodes { __typename id title } } }}"@$body=@{ query=$query } |ConvertTo-Json-Depth 5-Compress
$response=Invoke-RestMethod`-Uri "https://api.github.com/graphql"`-Method POST `-Headers $headers`-Body $body`-ContentType "application/json"$response.errors$response.data.repository.projectsV2.nodes|Select-Object id, title

API Reference

mdToProject(projectId: string, githubToken: string, sourcePath: string)

Import Multi-Story markdown files from a directory into a GitHub Project. Create-only and idempotent by Story ID.

• projectId: GitHub Project V2 ID
• githubToken: GitHub personal access token
• sourcePath: Path to directory containing markdown files

projectToMd(projectId: string, githubToken: string, outputPath?: string)

Export GitHub Project items to Single-Story markdown files. Defaults to writing into ./stories when no output path is provided.

• projectId: GitHub Project V2 ID
• githubToken: GitHub personal access token
• outputPath (optional): Output directory path. Defaults to './stories'

Story File Formats

Two complementary formats are supported:

• Multi-Story files (for mdToProject() import)
• Single-Story files (for projectToMd() export)

Multi-Story format (md→project)

Sections represent status. Each story must include - Story:, story id:, and description:.

## Backlog
- Story: Setup development environment
Story ID: Story-001
Description:
- Install required tools
- Configure IDE
- Setup version control
## Ready
- Story: Implement authentication
Story ID: Story-002
Description:
- Design flows
- Implement backend
- Integrate frontend
## In review
- Story: Improve accessibility
Story ID: Story-003
Description:
- Audit key screens
- Fix critical issues

Rules:

• Allowed headings: Backlog, Ready, In progress, In review, Done
• Aliases: To do → Ready, In Progress/in progress → In progress
• Unrecognised headings map to Backlog
• story id must be unique; existing IDs in Project are skipped (no update, no delete)
• Within a file, duplicate IDs: only the first entry is honoured; later duplicates are skipped
• description: content is free-form Markdown and preserved verbatim

Single-Story format (project→md, read-only)

Each file contains exactly one story and includes a Story ID section.

## Story: Setup development environment
### Story ID
Story-001
### Status
In progress
### Description
- Install required tools
- Configure IDE
- Setup version control

This format is generated by export and must not be used for import.

Status mapping

mdToProject() normalises headings/status strings using the logic in src/markdown-to-project.ts:

Input heading / status	Stored status
Backlog	Backlog
Ready, To do, Todo	Ready
In progress, In Progress	In Progress
In review	In review
Done	Done
Any other heading	Treated as Backlog

Import and Export Behaviour

• md→project (import)
  • Input: Multi-Story files only
  • Action: Create new items when story id does not exist in Project; skip otherwise
  • No updates or deletes from Markdown
• project→md (export)
  • Output: Multiple Single-Story files, each with ### Story ID
  • Read-only: do not feed these files back into import

Limitations and caveats

• The importer is create-only. Updating or deleting existing project items must be done in GitHub Projects.
• Exporters overwrite files with the same name inside the target directory.
• All commands expect PROJECT_ID and GITHUB_TOKEN to be available; the GitHub token must allow Projects and repo read access.
• Large exports/imports may trigger GitHub API rate limits. Use --dry-run to validate before executing.
• story id matching is case-insensitive, but duplicates in the same markdown file keep only the first occurrence.

Story ID

• Matching uses Story ID only; titles never overwrite existing items
• If an item with the same ID exists in Project: skip
• Missing story id: strictly skipped and logged with file name, start line, and title
• Missing ID plus exact title match triggers an additional "Possible title duplicate" warning

Dry-run and Diagnostics

Use dry-run to preview planned operations, with logs covering create plans, skip reasons, missing IDs, duplicates, and unknown keys. Ideal for CI gates and author feedback.

Migration (≤0.1.10 → 0.1.11)

• Move from per-story import files to a Multi-Story import file
• Ensure each story has a unique story id
• Keep edits and deletions within GitHub Project; do not attempt to overwrite via Markdown
• Update scripts or automation to use the new CLI entry points

Deprecated

• src/story-to-project-item.ts is deprecated as an import entry. Use src/markdown-to-project.ts via the CLI or library.

GitHub Actions

MD Sync

name: MD Syncon:
push:
paths:
- examples/md/**/*.mdworkflow_dispatch:
jobs:
sync:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4with:
node-version: 20cache: npm
- run: npm ci
- env:
PROJECT_ID: ${{ secrets.PROJECT_ID }}GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}run: npx ts-node examples/md-to-project.ts

Daily Project to MD

name: Daily Project to MDon:
schedule:
- cron: "0 16 * * *"workflow_dispatch:
jobs:
export:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4with:
node-version: 20cache: npm
- run: npm ci
- env:
PROJECT_ID: ${{ secrets.PROJECT_ID }}GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}run: npx ts-node examples/project-to-md.ts examples/items

Notes

• Requires Node.js 18+
• Runs in Node.js/server environments, not in the browser

Feedback

If you encounter any problems during use, or have suggestions for improvement, feel free to contact me:

• 🌐 Personal Website: https://nzlouis.com
• 📝 Blog: https://blog.nzlouis.com
• 💼 LinkedIn: https://www.linkedin.com/in/ailouis
• 📧 Email: nzlouis.com@gmail.com

You are also welcome to submit feedback directly in GitHub Issues 🙌

---

If you find this tool helpful, please consider giving it a ⭐️ Star on GitHub to support the project, or connect with me on LinkedIn.