Export GitHub issues to Markdown files

19. July 2025 397 words 2 minutes

Contents

I recently wanted to export issues of a few GitHub repositories and store them in Markdown files. I also liked additional data like state, labels and comments included in a nice format. So I made a script.

This could come in handy for preserving issues and discussions before deleting a repository, or as a backup of issues of a repo that you do not have control over.

Requirements

GitHub CLI (gh)
Zsh

Script

The script defines a root BACKUP_DIR (default: $HOME/backup).

Any exported issues will be saved in an issues sub-directory, then repository owner and repo name, e.g. issues/abstrask/flux-helm-difF.

A separate Markdown file named issue-#.md (where # is the issue number) will be created.

The backup_repo_issues variable is an array, with each full repository name (owner/repo) on separate lines.

#!/usr/bin/env zsh
set -eu

export BACKUP_DIR="$HOME/backup"
mkdir -p "${BACKUP_DIR}"

backup_repo_issues=(
  abstrask/flux-helm-diff
  dfds/aws-inventory-orchestrator
)

for repo in "${backup_repo_issues[@]}"; do
  repo_dir="${BACKUP_DIR}/repo_issues/${repo}"
  mkdir -p "${repo_dir}"
  issue_numbers=("${(f)$(gh issue list --repo "${repo}" --state all --json number --jq '.[].number')}")
  echo -n "Saving ${#issue_numbers} issues from repo \"$repo\":"
  for number in $issue_numbers; do
    echo -n " $number"
    gh issue view "$number" --repo "${repo}" \
    --json number,title,body,url,state,comments,labels --template \
'# [{{.title}} #{{.number}} ({{.state}})]({{.url}})
{{- if .labels }}

**Labels:** {{range .labels}}[{{.name}}] {{end}}
{{- end}}

{{.body}}{{range .comments}}

---
**Comment by @{{.author.login}} at {{.createdAt}}**

{{.body}}{{end}}
' > "${repo_dir}/issue-${number}.md"
  done
  echo
done

Info

The script exports the raw markdown from the GitHub issues. URLs to images are maintained and typically refer to an Amazon S3 bucket, and includes a token.

I haven’t checked the duration of this token, but I’ll assume it will eventually expire, rendering embedded images unloadable.

To workaround this, you’d probably have to parse the markdown file, recognise any image references, download the image and replace the URL.

Example

This is the console output when running the script with the example repos:

$ ./github_issues.sh
Saving 7 issues from repo "abstrask/flux-helm-diff": 15 12 11 10 7 6 5
Saving 12 issues from repo "dfds/aws-inventory-orchestrator": 164 20 16 9 8 7 6 5 4 3 2 1

The exported Markdown for issue #12 for my Flux Helm Diff GitHub Action, looks like this:

# [Enable dry-running charts that rely on KubeVersion, similar to ApiVersions #12 (CLOSED)](https://github.com/abstrask/flux-helm-diff/issues/12)

Just like `.Capabilities.ApiVersions`, many charts make use of the `.Capabilities.KubeVersion` built-in object to determine how they're rendered.

This should also be possible to emulate.

---
**Comment by @abstrask at 2024-10-15T12:39:52Z**

Solved by #13