Metadata-Version: 2.4
Name: navig-github
Version: 0.3.0
Summary: The full GitHub toolbox (backup, mirror, export, manage): its own navig-github command, and `navig github` inside navig.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,github,git,backup,mirror
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.7.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: schedule>=1.2.0
Provides-Extra: vault
Requires-Dist: navig-vault>=0.7.0; extra == "vault"
Dynamic: license-file

# navig-github

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> The full GitHub toolbox (backup, mirror, export, manage): its own navig-github command, and `navig github` inside navig.

**Works on its own** — its own CLI, no navig required · v0.3.0 · [PyPI](https://pypi.org/project/navig-github/)

**On its own** (no navig needed)

```bash
pip install navig-github
navig-github --help   # no navig needed
```

**With navig**

```bash
pip install "navig[github]"
navig github --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig github analytics` | Analyze backup directory and generate statistics report. |
| `navig github analytics-history` | Show backup history and statistics. |
| `navig github attachments` | Download attachments (images, files) from issues and pull requests. |
| `navig github backup` | 📦 Clone / mirror every repo for a user (or --org organisation). |
| `navig github clone` | ⬇️  Clone a single repository (with the full toolbox if available, else plain git). |
| `navig github config-delete` | Delete a saved backup profile. |
| `navig github config-export` | Export a profile to a file for sharing. |
| `navig github config-import` | Import a profile from a file. |
| `navig github config-list` | List all saved backup profiles. |
| `navig github config-load` | Load and display a saved backup profile. |
| `navig github config-save` | Save a backup configuration profile. |
| `navig github delete` | Delete a GitHub repository. |
| `navig github diff` | Compare two backup directories and show differences. |
| `navig github discussions` | Export all discussions from a GitHub repository. |
| `navig github followers` | Export followers (and optionally following) for a GitHub user. |
| `navig github gists` | Backup all gists for a user. |
| `navig github issues` | Export all issues from a GitHub repository. |
| `navig github labels` | Export all labels from a GitHub repository. |
| `navig github milestones` | Export all milestones from a GitHub repository. |
| `navig github notify-status` | Show notification configuration status. |
| `navig github notify-test` | Test all configured notification providers. |
| `navig github org` | Backup all repositories for a GitHub organization. |
| `navig github profile` | Export GitHub user profile information. |
| `navig github projects` | Export GitHub Projects (v2) for a user/org or repository. |
| `navig github pulls` | Export all pull requests from a GitHub repository. |
| `navig github releases` | Download all releases and assets from a GitHub repository. |
| `navig github repo` | Backup a single GitHub repository with optional data exports. |
| `navig github restore-issues` | Restore issues from a backup to a GitHub repository. |
| `navig github restore-labels` | Restore labels from a backup to a GitHub repository. |
| `navig github restore-milestones` | Restore milestones from a backup to a GitHub repository. |
| `navig github restore-releases` | Restore releases from a backup to a GitHub repository. |
| `navig github schedule-add` | Add a scheduled backup. |
| `navig github schedule-list` | List all scheduled backups. |
| `navig github schedule-remove` | Remove a scheduled backup. |
| `navig github schedule-run` | Run the backup scheduler daemon. |
| `navig github search` | 🔍 Search GitHub and clone matching repositories. |
| `navig github secrets` | Export repository secrets (names only, not values). |
| `navig github snapshot` | Create a snapshot of the current backup state for later comparison. |
| `navig github starred` | Mirror all repositories starred by a user. |
| `navig github status` | ℹ️  Show engine installation status and token configuration. |
| `navig github template-create` | Create a custom backup template. |
| `navig github template-delete` | Delete a custom template (built-in templates cannot be deleted). |
| `navig github template-show` | Show details of a backup template. |
| `navig github template-use` | Run a backup using a template. |
| `navig github templates` | List available backup templates. |
| `navig github token remove` | 🗑  Remove the stored GitHub token. |
| `navig github token set` | 🔑 Save a GitHub token for navig github to use automatically. |
| `navig github token show` | 🔍 Display where the current GitHub token comes from (masked). |
| `navig github transfer` | Transfer repository(ies) to a GitHub organization. |
| `navig github user` | Backup all repositories for a GitHub user. |
| `navig github verify` | Verify backup integrity. |
| `navig github watched` | Mirror all repositories watched by a user. |
| `navig github webhooks` | Export webhooks configuration from a GitHub repository. |
| `navig github wiki` | Backup a repository's wiki (if it exists). |
| `navig github workflows` | Backup GitHub Actions workflows from a repository. |

</details>

<!-- navig:plugin-card:end -->

NAVIG GitHub module — the **full GitHub toolbox** (backup, mirror, export, restore,
analytics, scheduling) wired natively into `navig github`. A first-party navig plugin
(free, toggleable).

**License:** Apache-2.0 · **Version:** 0.2.0

## What it is

`navig-github` is a **first-party NAVIG plugin** — it extends NAVIG itself (CLI verbs +
gateway routes), and it is free and toggleable. Plugins are different from
*blocks*: a plugin adds capabilities to the platform; a block is an outcome you
*apply* with `navig apply`.

The GitHub engine is bundled in-package (`navig_github.engine`) and
mounted **in-process**: every engine command is a `navig github` subcommand, and a
group callback injects the vault token (`github_token`) into `GITHUB_TOKEN` so the
whole surface authenticates automatically.

```
navig github token set <PAT>          # store the token in the navig vault, once
navig github backup <user> -y         # mirror every repo (curated wrapper)
navig github issues owner/repo        # export issues (in-process)
navig github releases owner/repo      # download releases + assets
navig github verify ./mirrors         # backup integrity check
navig github --help                   # the full surface, grouped by panels
```

## Install

It ships in the NAVIG monorepo and loads automatically when NAVIG is installed.
To add/enable it explicitly:

```
navig plugin add navig-github
```

Check wiring and toggle state:

```
navig store list
```

## Development

This package lives in the NAVIG monorepo under `plugins/navig-github/`. It registers via
the `navig.plugins` entry-point group; CLI verbs register via `navig.commands`.
