Skip to content
ProGit Docs

Migrate from GitHub Issues

import { Steps } from ‘@astrojs/starlight/components’;

GitHub Issues live in GitHub’s database. You cannot version them, cannot audit them offline, and cannot sync them without GitHub’s permission. Migrating to ProGit moves your project state into .project/ inside your repo — tracked in git, owned by you, syncable to every clone without a vendor in the path.

The end state

Section titled “The end state”

After migration:

  • Source of truth — .project/issues/*.json in your git repo. git log -- .project/ is your project history.
  • Agents — write issues via prog issue create|set|note --json. No browser, no API tokens for writes.
  • Board — prog board or prog ui. Moves stage locally; prog sync commits and pushes.
  • GitHub — optional federation bridge. prog sync --to forgejo (or GitLab) keeps a forge mirror in sync if you want one. If you don’t, you can drop the forge entirely.

Migration path

Section titled “Migration path”

  1. Initialize ProGit in your repo

    Terminal window
    cd your-project
    prog init
    # creates .project/config.kdl and .project/issues/

  2. Export your GitHub Issues

    Use GitHub’s issue export (or the gh CLI) to pull your issues as JSON. Each issue becomes a .project/issues/<id>.json file. ProGit’s issue schema maps the common fields:

    • title → title
    • body → description
    • number → preserved as a reference field
    • labels → tags
    • state (open/closed) → status (backlog/in-progress/done)

  3. Commit the initial import

    Terminal window
    git add .project/
    git commit -m "progit: import issues from GitHub"
    git push

    Every clone now has your full project history.

  4. Point your agents at the CLI

    Replace GitHub-issue-creating prompts with:

    Terminal window
    prog issue create --title "..." --actor agent:voxis --json

  5. Optional: keep a forge federation bridge

    If some stakeholders still want a web view, keep a Forgejo/GitLab mirror and use prog sync --to forgejo as a one-way or bidirectional bridge. The bridge is optional; git-native works without it.

What you gain

Section titled “What you gain”
  • Versioned project state — git blame .project/issues/abc123.json shows who moved the ticket, when, why.
  • Offline-first — create, move, and search issues with no network.
  • Agent-native — machines write through a stable CLI; no API rate limits, no auth tokens for writes.
  • No vendor lock-in — your project state is plain files in a repo you control. If ProGit disappears tomorrow, your issues are still readable JSON.

What you give up

Section titled “What you give up”
  • GitHub’s web UI for issues — by design. The whole point. If you need a web view, run a Forgejo mirror and use prog sync --to forgejo.
  • GitHub project boards — replaced by prog board / prog ui, with sync-as-commit semantics GitHub cannot offer.