|
| 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