Deploy a Marketplace Skill to GitHub via Pull Request¶

This guide walks one full flow three ways. The mental model is the same in every surface:

Find — search the marketplace for a skill.
Install — install it into your collection (adds a collection artifact).
Deploy via PR — open a pull request that adds that artifact's files to a GitHub repository.

The deploy step never pushes to a branch directly; it always opens a Pull Request against a base branch (default main).

Two deploy modes¶

Mode	How you point at the repo	Auth	Typical use
mode-a (connection)	`connection_id` of a registered Git Repo Connection	Stored with the connection	Enterprise — admins register repos once via the Git Repo Connector
mode-b (transient)	`repo_url` (`owner/repo`, HTTPS, or SSH) + an ephemeral `token`	Write-only token supplied per request, never persisted	Any edition / one-off repos

You supply either connection_id or repo_url — never both.

Prerequisites¶

An authenticated session (a non-admin integrator key is sufficient — deploy uses ordinary write-scope auth).
Write access to the target GitHub repository.
For mode-a: a registered Git Repo Connection (Enterprise). For mode-b: a GitHub PAT with write access to the repo.

Web UI¶

Search — open the Marketplace and search for the skill you want.
Install — open the listing and install it. The skill is imported into your active collection as an artifact.
Open the deploy dialog — there are several entry points to the same DeployToRepoDialog:
Immediately after install, the install dialog shows a "Deploy to repo" affordance ("Deploy this artifact to a Git repository as a pull request").
From the artifact's detail view, click "Deploy to repo".
From a project that has a linked repo, use the "Deploy to Repository" panel (this prefills mode-a from the project's Git Repo Connection).
Choose a mode — the dialog ("Deploy to repository") shows two options:
Connection (mode-a): pre-selected and pre-filled when a connected repo is available; disabled with explanatory copy when none exists.
Transient (mode-b): enter the Repository URL (https://github.com/owner/repo), a Branch (defaults to main), and a GitHub token (ghp_...). The token field is write-only and is wiped when the dialog closes.
Optionally set a custom destination path (defaults to .skillmeat/<type>/<artifact>/).
Dry-run preview — click "Dry-run preview" to see the planned branch and the list of file changes. Nothing is written to the remote.
Submit — click "Open PR". On success a toast shows the new branch and the PR link. Follow the PR URL to review and merge. If an open PR already exists for this artifact, the deploy is an idempotent skip.

CLI¶

The marketplace and deploy commands are separate verbs. Human-readable text is the default; add --format json for machine output.

# 1. Search the marketplace
skillmeat marketplace-search "code review"
#    → table of listings; note the Listing ID column

# 2. Install the chosen listing into your collection
skillmeat marketplace-install skillmeat-42
#    → imports the bundle into your active collection (use --collection to target another)

# 3a. Dry-run preview first (no PR is created)
skillmeat deploy-to-repo my-skill \
  --repo-url owner/repo \
  --branch main \
  --preview

# 3b. Deploy via PR — mode-b (transient repo + ephemeral token)
#     Supply the token via the SKILLMEAT_DEPLOY_TOKEN env var so it never
#     appears in shell history or process args:
export SKILLMEAT_DEPLOY_TOKEN=ghp_your_write_scoped_pat
skillmeat deploy-to-repo my-skill --repo-url owner/repo --branch main
#     (If --repo-url is given without a token, you are prompted with hidden input.)

# 3c. Deploy via PR — mode-a (registered Git Repo Connection)
skillmeat deploy-to-repo my-skill --connection-id 5

# 4. Check deployment status later (PR may be pending right after submit)
skillmeat deploy-to-repo my-skill --status DEPLOYMENT_ID

Notes: - --connection-id and --repo-url are mutually exclusive; you must pass exactly one. - --dest-path overrides the default .skillmeat/<type>/<name>/ destination. - --collection selects the source collection (defaults to the active one).

API¶

All /api/v1/* routes require auth. Deploy uses ordinary write-scope auth (owner_scope defaults to user; all is rejected). The token field is write-only — never logged, persisted, or returned.

AUTH='-H "Authorization: Bearer $SKILLMEAT_API_TOKEN"'

# 1. Search the marketplace catalog
curl -s -H "Authorization: Bearer $SKILLMEAT_API_TOKEN" \
  "http://localhost:8080/api/v1/marketplace/catalog/search?q=code+review&type=skill&limit=20"

# 2. Install a listing into the collection
curl -s -X POST -H "Authorization: Bearer $SKILLMEAT_API_TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/api/v1/marketplace/install" \
  -d '{"listing_id": "skillmeat-42", "strategy": "interactive"}'

# 3. Dry-run preview (opens nothing; returns deploy_branch + file_changes)
curl -s -X POST -H "Authorization: Bearer $SKILLMEAT_API_TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/api/v1/artifacts/my-skill/deploy-to-repo/preview" \
  -d '{"repo_url": "https://github.com/owner/repo", "branch": "main"}'

# 4a. Deploy via PR — mode-b (transient repo + write-only token)
curl -s -X POST -H "Authorization: Bearer $SKILLMEAT_API_TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/api/v1/artifacts/my-skill/deploy-to-repo" \
  -d '{"repo_url": "https://github.com/owner/repo", "branch": "main", "token": "ghp_..."}'

# 4b. Deploy via PR — mode-a (registered connection)
curl -s -X POST -H "Authorization: Bearer $SKILLMEAT_API_TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/api/v1/artifacts/my-skill/deploy-to-repo" \
  -d '{"connection_id": 5}'

# 5. Poll deployment status (pr_url may be null until the PR is created)
curl -s -H "Authorization: Bearer $SKILLMEAT_API_TOKEN" \
  "http://localhost:8080/api/v1/artifacts/my-skill/deploy-to-repo/DEPLOYMENT_ID"

The deploy response returns deployment_id, pr_url, pr_number, status, mode, deploy_branch, and skipped (true when an existing open PR is reused).

Editions¶

The deploy-to-repo feature works in both editions; only the surrounding posture differs.

Aspect	Local	Enterprise
Backend	SQLite + filesystem, single-tenant	PostgreSQL, multi-tenant (tenant scoping applied)
mode-a connections	Git Repo Connection registry typically unused	Registered connections are the standard path (admin-managed)
mode-b (repo_url + token)	Fully supported — the usual path	Supported for one-off repos
Auth	Local provider, zero-config	Integrator key / non-admin write scope; deploys are tenant-scoped

mode-b (arbitrary repo + ephemeral token) works everywhere; mode-a (connection registry) is the typical Enterprise path.