Skip to content

Per-Project Upstream Integration Guide

SkillMeat tracks two related, but distinct, pieces of provenance once an artifact has been imported: where it came from upstream (an upstream binding, linking a local artifact back to the GitHub release or ref it was imported from) and which project it belongs to (a project-artifact association, tracking membership in a project's deployed artifact set). This guide covers both, and clarifies how they differ from Git Connections.

How this differs from Git Connections

These are three related but separate concepts:

Concept What it tracks Where it's covered
Git Connection A GitHub repository + branch you scan to discover artifacts to import Git Connections Guide
Upstream Binding Which GitHub release/ref an already-imported artifact came from, so SkillMeat can detect newer upstream versions This guide
Project-Artifact Association Which artifacts are current members of a project's deployed set (enterprise governance) This guide

A Git Connection answers "what repository should I scan for artifacts?" An upstream binding answers "which upstream release is this specific artifact pinned to?" A project-artifact association answers "which artifacts does this project currently own?"

A capture side-effect worth knowing about: when you run skillmeat project register from inside a project directory that has a local git remote, SkillMeat auto-detects that remote and — in enterprise mode — automatically creates and links a Git Connection to the project as a side effect of registration. It shows up in that project's Git Sources tab exactly as if you had linked it manually (see the Git Connections Guide). This capture is best-effort and never blocks project creation if it fails.

Upstream Bindings

An upstream binding is a database row that records the relationship between one local artifact and the upstream GitHub release or ref it was imported from — for example, binding_kind: imported_from pinned to a specific release.

How a binding is created

Bindings are created automatically as a side effect of importing an artifact from a GitHub source — you don't need to create one by hand for artifacts imported through the normal import flow. There is no interactive "create a binding" step in the CLI or web UI; the POST endpoint below exists for programmatic/administrative use (e.g., backfilling artifacts that were imported before this feature existed).

API surface

Upstream bindings are exposed only through the HTTP API today — there is no CLI command that wraps binding create/list/update, in either edition. All three endpoints require authentication (Authorization header per your deployment's auth setup) and work identically for local and enterprise editions (the server routes to the edition-appropriate repository internally).

Method Path Purpose
POST /api/v1/artifacts/{artifact_id}/upstream-bindings Create a binding (idempotent — returns the existing row if one already matches)
GET /api/v1/artifacts/{artifact_id}/upstream-bindings List bindings for an artifact (cursor-paginated)
PATCH /api/v1/artifacts/{artifact_id}/upstream-bindings/{binding_id} Update pin_policy and/or source_release_id on an existing binding

{artifact_id} is the artifact's type:name composite identifier (e.g. skill:canvas-design), URL-encoded if it contains characters that need it.

List an artifact's bindings:

curl -s "$SKILLMEAT_API_URL/api/v1/artifacts/skill:canvas-design/upstream-bindings" \
  -H "Authorization: Bearer $SKILLMEAT_TOKEN"

Update the pin policy on an existing binding:

curl -s -X PATCH \
  "$SKILLMEAT_API_URL/api/v1/artifacts/skill:canvas-design/upstream-bindings/42" \
  -H "Authorization: Bearer $SKILLMEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pin_policy": "track_latest_release"}'

Valid binding_kind values: imported_from, forked_from, synced_from, promoted_from.

Valid pin_policy values: snapshot_on_change (default), track_latest_release, track_tags, manual_pin. For what each policy means and how to choose one, see the Pin Policy Reference — that guide covers policy semantics in depth and applies to bindings managed through this API.

Current limitations

  • No CLI command lists, creates, or updates bindings directly. If you need to inspect or change a binding today, use the API endpoints above.
  • No dedicated web UI panel for viewing or editing a binding is wired into the artifact detail page yet. If your artifact was imported from GitHub, you can still confirm whether diffing against upstream is available (a related but separate capability) from the artifact's Sync tab — see Syncing Changes.
  • Artifacts imported before this feature shipped may have no binding at all. An administrator can backfill these from source_url using a maintenance script — ask your SkillMeat administrator if hasValidUpstreamSource-dependent features (like upstream diffing) seem unavailable for an artifact you'd expect to have upstream tracking.

Project-Artifact Association (Enterprise)

In enterprise deployments, SkillMeat separately tracks which artifacts are members of each project's deployed set, in a dedicated table distinct from the artifact catalog itself. This is what lets governance and audit views answer "what's actually deployed to Project X" without re-scanning the filesystem.

This association is populated and verified through two enterprise-only CLI commands. Both require enterprise mode to be active (they exit with an error otherwise) and operate tenant-wide by default.

Provisioning project membership

skillmeat enterprise provision-project [--project-id UUID] [--tenant-id UUID] [--dry-run / --no-dry-run] [--json]

Resolves each project's intended artifact set from your tenant's configured baseline and project-default deployment sets, and reconciles it against the project's actual artifact membership: it adds any missing intended member and classifies existing rows, but never deletes or prunes a row. Use --dry-run to preview drift before writing.

# Preview drift for every project in the tenant, machine-readable
skillmeat enterprise provision-project --dry-run --json

# Provision a specific project
skillmeat enterprise provision-project --project-id <uuid>

Re-running this command against an already-provisioned project is safe — it won't duplicate rows.

Verifying project membership

skillmeat enterprise verify-project-artifacts [--project-id UUID] [--tenant-id UUID] [--json]

A read-only check: compares each project's intended artifact set against the actual rows in the database and reports what's missing, what's extra (present but not intended — this legitimately includes artifacts classified as ephemeral, which is expected, not an error), and what's unresolved. It also reports tenant-wide totals for project-artifact associations and upstream bindings, which is a quick way to sanity-check that both features are populated.

skillmeat enterprise verify-project-artifacts --json

Note: this is distinct from skillmeat project reconcile --json, which scans your local filesystem manifest rather than querying the database — it cannot confirm the actual state of enterprise_project_artifacts. Use verify-project-artifacts when you need to confirm database-level truth.

Current limitations

  • Provisioning and verification are CLI-only, enterprise-only, and tenant/admin-scoped — there is no self-service web UI for an individual project owner to trigger provisioning or view association drift today.
  • Provisioning requires baseline and project-default deployment sets to already be configured for your tenant; an unconfigured tenant provisions nothing and reports every existing row as ephemeral.

Local vs. enterprise editions

  • Upstream bindings exist in both editions — the API create/list/update endpoints work identically, just backed by different storage.
  • Project-artifact association (provision-project, verify-project-artifacts) is enterprise-only. The local edition has no equivalent concept of tracked per-project artifact membership distinct from your collection itself.