Skip to content

Commit 704b0c5

Browse files
joshjohanningCopilotCopilot
authored
feat: add script to export GitHub Projects V2 board to Markdown (#167)
* feat: add script to export GitHub Projects V2 board to Markdown * docs: update script description Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix: align script header comment and README with actual slugified filename behavior Agent-Logs-Url: https://github.com/joshjohanning/github-misc-scripts/sessions/00189b49-0cc0-4114-96f4-9345a93653b7 Co-authored-by: joshjohanning <19912012+joshjohanning@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent 7b35d61 commit 704b0c5

2 files changed

Lines changed: 378 additions & 0 deletions

File tree

‎gh-cli/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -606,6 +606,27 @@ Features:
606606
> [!NOTE]
607607
> This requires admin access to the repositories. For private repositories, the organization must have GitHub Advanced Security enabled.
608608
609+
### export-project-board-to-markdown.sh
610+
611+
Exports a GitHub Projects V2 board to a clean Markdown file suitable for sharing (e.g., customer-facing deliverables).
612+
613+
Usage:
614+
615+
```shell
616+
./export-project-board-to-markdown.sh my-org 123
617+
./export-project-board-to-markdown.sh my-org 123 custom-output.md
618+
```
619+
620+
The generated Markdown includes:
621+
622+
- Clickable Table of Contents
623+
- Issue/PR details with links and metadata
624+
- Custom field values (Status, Priority, etc.)
625+
- Raw Markdown formatting for bodies and comments (preserving headings, lists, code fences, blockquotes)
626+
627+
> [!NOTE]
628+
> Works with Projects V2 (newer project boards). Find the project number in the URL: `github.com/orgs/ORG/projects/NUMBER`. If no output file is specified, defaults to a slugified project title such as `<project-title-slug>.md` (lowercase with non-alphanumeric characters replaced by `-`)
629+
609630
### find-attachments-in-repositories.sh
610631

611632
Finds attachments in issues, pull requests, and optionally, issue/pull request comments. This finds both screenshots and file attachments.
Lines changed: 357 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,357 @@
1+
#!/bin/bash
2+
3+
# Export a GitHub Projects V2 board to a clean Markdown file suitable for sharing
4+
# (e.g. as a customer-facing engagement deliverable).
5+
#
6+
# Differences from get-project-board-items.sh:
7+
# - Outputs valid Markdown (headings, links, tables) instead of decorated terminal text
8+
# - Issue / PR bodies and comments are emitted as raw Markdown so embedded
9+
# headings, lists, task lists, code fences, and blockquotes render correctly
10+
# - Generates a clickable Table of Contents
11+
# - Writes to a file (default: slugified project title, e.g. <project-title-slug>.md) instead of stdout
12+
#
13+
# Usage: ./export-project-board-to-markdown.sh <org> <project-number> [output-file]
14+
# Example: ./export-project-board-to-markdown.sh my-org 123
15+
# Example: ./export-project-board-to-markdown.sh my-org 123 smbc-export.md
16+
17+
set -euo pipefail
18+
19+
if [ $# -lt 2 ] || [ $# -gt 3 ]; then
20+
echo "Usage: $0 <org> <project-number> [output-file]"
21+
echo "Example: ./export-project-board-to-markdown.sh my-org 123"
22+
echo "Example: ./export-project-board-to-markdown.sh my-org 123 smbc-export.md"
23+
echo ""
24+
echo "Note: This script works with Projects V2 (the newer project boards)"
25+
echo "To find project number, check the URL: github.com/orgs/ORG/projects/NUMBER"
26+
exit 1
27+
fi
28+
29+
org="$1"
30+
project_number="$2"
31+
output_file="${3:-}"
32+
33+
echo "🔍 Fetching project board items for project #$project_number in $org..." >&2
34+
35+
response=$(gh api graphql --paginate -f org="$org" -F projectNumber="$project_number" -f query='
36+
query($org: String!, $projectNumber: Int!, $endCursor: String) {
37+
organization(login: $org) {
38+
projectV2(number: $projectNumber) {
39+
title
40+
url
41+
items(first: 100, after: $endCursor) {
42+
nodes {
43+
id
44+
content {
45+
__typename
46+
... on Issue {
47+
title
48+
body
49+
number
50+
url
51+
state
52+
createdAt
53+
author { login }
54+
repository { name owner { login } }
55+
labels(first: 20) { nodes { name } }
56+
assignees(first: 10) { nodes { login } }
57+
comments(first: 100) {
58+
nodes {
59+
body
60+
author { login }
61+
createdAt
62+
}
63+
}
64+
}
65+
... on PullRequest {
66+
title
67+
body
68+
number
69+
url
70+
state
71+
merged
72+
createdAt
73+
author { login }
74+
repository { name owner { login } }
75+
labels(first: 20) { nodes { name } }
76+
assignees(first: 10) { nodes { login } }
77+
comments(first: 100) {
78+
nodes {
79+
body
80+
author { login }
81+
createdAt
82+
}
83+
}
84+
}
85+
... on DraftIssue {
86+
title
87+
body
88+
createdAt
89+
creator { login }
90+
}
91+
}
92+
fieldValues(first: 100) {
93+
nodes {
94+
... on ProjectV2ItemFieldTextValue {
95+
text
96+
field { ... on ProjectV2FieldCommon { name } }
97+
}
98+
... on ProjectV2ItemFieldSingleSelectValue {
99+
name
100+
field { ... on ProjectV2FieldCommon { name } }
101+
}
102+
... on ProjectV2ItemFieldIterationValue {
103+
title
104+
field { ... on ProjectV2FieldCommon { name } }
105+
}
106+
... on ProjectV2ItemFieldDateValue {
107+
date
108+
field { ... on ProjectV2FieldCommon { name } }
109+
}
110+
... on ProjectV2ItemFieldNumberValue {
111+
number
112+
field { ... on ProjectV2FieldCommon { name } }
113+
}
114+
}
115+
}
116+
}
117+
pageInfo { endCursor hasNextPage }
118+
}
119+
}
120+
}
121+
}
122+
' 2>&1) || {
123+
if echo "$response" | grep -q "INSUFFICIENT_SCOPES"; then
124+
echo "❌ Error: Your GitHub token doesn't have the required permissions" >&2
125+
echo "🔐 Required scope: 'read:project'" >&2
126+
echo "Run: gh auth refresh -h github.com -s read:project" >&2
127+
elif echo "$response" | grep -q "Could not resolve to a ProjectV2"; then
128+
echo "❌ Error: Project #$project_number not found in organization '$org'" >&2
129+
else
130+
echo "❌ Error fetching project data:" >&2
131+
echo "$response" >&2
132+
fi
133+
exit 1
134+
}
135+
136+
project_title=$(echo "$response" | jq -r '.data.organization.projectV2.title // "Unknown Project"' | head -n 1)
137+
project_url=$(echo "$response" | jq -r '.data.organization.projectV2.url // ""' | head -n 1)
138+
139+
# Default output filename: slugified project title
140+
if [ -z "$output_file" ]; then
141+
slug=$(echo "$project_title" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g')
142+
output_file="${slug:-project-export}.md"
143+
fi
144+
145+
echo "📝 Writing Markdown to: $output_file" >&2
146+
147+
# Collect all items across paginated responses into a single JSON array
148+
items_json=$(echo "$response" | jq -s '[.[] | .data.organization.projectV2.items.nodes[]?]')
149+
150+
total=$(echo "$items_json" | jq 'length')
151+
152+
{
153+
echo "# $project_title"
154+
echo ""
155+
if [ -n "$project_url" ] && [ "$project_url" != "null" ]; then
156+
echo "**Project board:** [$project_url]($project_url)"
157+
echo ""
158+
fi
159+
echo "**Generated:** $(date -u +"%Y-%m-%d %H:%M UTC") "
160+
echo "**Total items:** $total"
161+
162+
# Status breakdown (from project Status field)
163+
status_summary=$(echo "$items_json" | jq -r '
164+
[ .[] | .fieldValues.nodes[]? | select(.field.name == "Status") | .name ]
165+
| group_by(.)
166+
| map({status: .[0], count: length})
167+
| sort_by(-.count)
168+
| map("\(.status): \(.count)")
169+
| join(" - ")
170+
')
171+
if [ -n "$status_summary" ] && [ "$status_summary" != "" ]; then
172+
echo " "
173+
echo "**Status breakdown:** $status_summary"
174+
fi
175+
echo ""
176+
echo "---"
177+
echo ""
178+
echo "## Table of Contents"
179+
echo ""
180+
181+
# Build TOC
182+
echo "$items_json" | jq -r '
183+
to_entries[] |
184+
.key as $i |
185+
.value as $item |
186+
($item.content.__typename // "ProjectItem") as $type |
187+
($item.content.title //
188+
([$item.fieldValues.nodes[]? | select(.field.name == "Title") | .text] | first) //
189+
"Untitled") as $title |
190+
($item.content.number // null) as $num |
191+
(if $num then "#\($num) - \($title)" else $title end) as $label |
192+
"- [\($i + 1). \($label)](#item-\($i + 1))"
193+
'
194+
echo ""
195+
echo "---"
196+
echo ""
197+
198+
# Emit each item
199+
count=$(echo "$items_json" | jq 'length')
200+
i=0
201+
while [ "$i" -lt "$count" ]; do
202+
item=$(echo "$items_json" | jq -c ".[$i]")
203+
idx=$((i + 1))
204+
205+
type=$(echo "$item" | jq -r '.content.__typename // "ProjectItem"')
206+
207+
# Resolve title
208+
title=$(echo "$item" | jq -r '.content.title // empty')
209+
if [ -z "$title" ]; then
210+
title=$(echo "$item" | jq -r '[.fieldValues.nodes[]? | select(.field.name == "Title") | .text] | first // "Untitled"')
211+
fi
212+
213+
number=$(echo "$item" | jq -r '.content.number // empty')
214+
url=$(echo "$item" | jq -r '.content.url // empty')
215+
repo_owner=$(echo "$item" | jq -r '.content.repository.owner.login // empty')
216+
repo_name=$(echo "$item" | jq -r '.content.repository.name // empty')
217+
state=$(echo "$item" | jq -r '.content.state // empty')
218+
merged=$(echo "$item" | jq -r '.content.merged // empty')
219+
author=$(echo "$item" | jq -r '.content.author.login // .content.creator.login // empty')
220+
created=$(echo "$item" | jq -r '.content.createdAt // empty')
221+
body=$(echo "$item" | jq -r '.content.body // empty')
222+
223+
# Heading
224+
case "$type" in
225+
Issue) icon="Issue" ;;
226+
PullRequest) icon="Pull Request" ;;
227+
DraftIssue) icon="Draft Issue" ;;
228+
*) icon="Project Card" ;;
229+
esac
230+
231+
if [ -n "$number" ]; then
232+
heading_title="#$number - $title"
233+
else
234+
heading_title="$title"
235+
fi
236+
237+
# Only prefix the heading with type for real Issues / Pull Requests; draft issues
238+
# and standalone project cards just use the title (type is still shown in the table).
239+
case "$type" in
240+
Issue|PullRequest)
241+
echo "## <a id=\"item-$idx\"></a>$idx. $icon: $heading_title"
242+
;;
243+
*)
244+
echo "## <a id=\"item-$idx\"></a>$idx. $heading_title"
245+
;;
246+
esac
247+
echo ""
248+
249+
250+
# Metadata table - emit rows in a fixed, predictable order:
251+
# Type, Repository, Link, State, Status, Day, Author, Created, Assignees, Labels,
252+
# then any remaining custom fields in their natural order.
253+
echo "| Field | Value |"
254+
echo "| --- | --- |"
255+
echo "| Type | $icon |"
256+
if [ -n "$repo_owner" ] && [ -n "$repo_name" ]; then
257+
echo "| Repository | \`$repo_owner/$repo_name\` |"
258+
fi
259+
if [ -n "$number" ] && [ -n "$url" ]; then
260+
echo "| Link | [#$number]($url) |"
261+
elif [ -n "$url" ]; then
262+
echo "| Link | [$url]($url) |"
263+
fi
264+
if [ -n "$state" ]; then
265+
if [ "$type" = "PullRequest" ] && [ "$merged" = "true" ]; then
266+
echo "| State | MERGED |"
267+
else
268+
echo "| State | $state |"
269+
fi
270+
fi
271+
272+
# Pull out Status and Day custom fields up front so they appear in a consistent slot.
273+
status_value=$(echo "$item" | jq -r '[.fieldValues.nodes[]? | select(.field.name == "Status") | (.text // .name // .title // .date // (.number | tostring?))] | first // empty')
274+
day_value=$(echo "$item" | jq -r '[.fieldValues.nodes[]? | select(.field.name == "Day") | (.text // .name // .title // .date // (.number | tostring?))] | first // empty')
275+
if [ -n "$status_value" ]; then
276+
echo "| Status | $status_value |"
277+
fi
278+
if [ -n "$day_value" ]; then
279+
echo "| Day | $day_value |"
280+
fi
281+
282+
if [ -n "$author" ]; then
283+
echo "| Author | @$author |"
284+
fi
285+
if [ -n "$created" ]; then
286+
created_fmt=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$created" "+%Y-%m-%d" 2>/dev/null || echo "$created")
287+
echo "| Created | $created_fmt |"
288+
fi
289+
290+
# Assignees
291+
assignees=$(echo "$item" | jq -r '[.content.assignees.nodes[]?.login] | map("@" + .) | join(", ")')
292+
if [ -n "$assignees" ]; then
293+
echo "| Assignees | $assignees |"
294+
fi
295+
296+
# Labels
297+
labels=$(echo "$item" | jq -r '[.content.labels.nodes[]?.name] | map("`" + . + "`") | join(", ")')
298+
if [ -n "$labels" ]; then
299+
echo "| Labels | $labels |"
300+
fi
301+
302+
# Remaining custom field values (Title/Description/Body excluded; Status/Day already emitted)
303+
echo "$item" | jq -r '
304+
.fieldValues.nodes[]?
305+
| select(.field.name != null
306+
and (.field.name | IN("Title", "Description", "Body", "Status", "Day") | not))
307+
| "| " + .field.name + " | " + (
308+
(.text // .name // .title // .date // (.number | tostring?)) // ""
309+
) + " |"
310+
'
311+
echo ""
312+
313+
# Description
314+
if [ -n "$body" ] && [ "$body" != "null" ]; then
315+
echo "### Description"
316+
echo ""
317+
# Emit raw markdown body so embedded formatting renders
318+
printf "%s\n" "$body"
319+
echo ""
320+
fi
321+
322+
# Comments (Issue / PR)
323+
comment_count=$(echo "$item" | jq '[.content.comments.nodes[]?] | length')
324+
if [ "$comment_count" -gt 0 ]; then
325+
echo "### Comments ($comment_count)"
326+
echo ""
327+
ci=0
328+
while [ "$ci" -lt "$comment_count" ]; do
329+
comment=$(echo "$item" | jq -c ".content.comments.nodes[$ci]")
330+
c_author=$(echo "$comment" | jq -r '.author.login // "unknown"')
331+
c_created=$(echo "$comment" | jq -r '.createdAt // ""')
332+
c_body=$(echo "$comment" | jq -r '.body // ""')
333+
if [ -n "$c_created" ]; then
334+
c_date=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$c_created" "+%Y-%m-%d %H:%M UTC" 2>/dev/null || echo "$c_created")
335+
else
336+
c_date="unknown date"
337+
fi
338+
echo "#### @$c_author - $c_date"
339+
echo ""
340+
if [ -n "$c_body" ] && [ "$c_body" != "null" ]; then
341+
printf "%s\n" "$c_body"
342+
else
343+
echo "_(no content)_"
344+
fi
345+
echo ""
346+
ci=$((ci + 1))
347+
done
348+
fi
349+
350+
echo "---"
351+
echo ""
352+
353+
i=$((i + 1))
354+
done
355+
} > "$output_file"
356+
357+
echo "✅ Done. Wrote $total items to $output_file" >&2

0 commit comments

Comments
 (0)