Skip to content

Pin Policy Reference

Pin policies control how SkillMeat tracks and selects upstream releases for artifacts imported from GitHub marketplace sources. This reference explains all four pin policies and the discover-mode default behavior.

Quick Reference

Policy Selection Method Use Case Auto-Advance
track_latest_release Automatic (latest stable) Stay current with releases Yes
snapshot_on_change Manual (on-demand) Conservative updates No
track_tags Git tags (manual selection) Flexible version control No
manual_pin User-specified release Strict version locking No

Pin Policy Breakdown

1. track_latest_release

Description: Automatically tracks and pulls the most recent stable (non-draft, non-prerelease) GitHub release.

How it works:

Available releases on GitHub:
  v3.0.0-beta.1  (prerelease - skip)
  v2.9.1         ← SELECTED (latest stable)
  v2.9.0         (older)
  v2.8.0 (draft) (draft - skip)

Your artifact automatically advances to v2.9.1

Eligible releases: - Must be a published release (not draft) - Must be non-prerelease (not -beta, -alpha, -rc, etc.) - Selected from most recent first in descending publish-date order

Ineligible releases (automatically skipped): - Draft releases - Pre-release versions (beta, alpha, RC) - Yanked or deprecated releases

When to use:

  • ✅ You want to stay current with upstream
  • ✅ You trust the upstream publisher's release process
  • ✅ Your artifact doesn't require manual testing before adoption
  • ✅ You have a team that reviews artifact updates regularly

When NOT to use:

  • ❌ You need to test before adopting major versions
  • ❌ Breaking changes in upstream affect your customizations
  • ❌ You maintain multiple stable versions

Example deployment:

# Binding set to track_latest_release for a data-processing skill
# Upstream releases v2.0, then v2.1

Initial sync:
  → Artifact set to v2.0

Upstream publishes v2.1:
  → Webhook notifies SkillMeat
  → Version check identifies v2.1 as latest stable
  → Next sync pulls v2.1 automatically

2. snapshot_on_change

Description: Takes a snapshot when upstream content changes; you manually decide when to pull new releases.

How it works:

Upstream releases v2.1.0

Initial sync:
  → Artifact pinned to v2.1.0 (snapshot created)

Upstream releases v2.2.0:
  → Webhook notifies SkillMeat
  → "Update available" flag set to true
  → Your artifact remains at v2.1.0 (no auto-pull)
  → You see "Update available" in the web UI

When you're ready:
  → Click "Pull Latest" to manually pull v2.2.0

Discovery mechanism:

When discovery mode is enabled (default), webhooks detect upstream changes and set an update_available flag. However, webhooks never force a local sync. Instead:

  1. Webhook detects change and sets flag
  2. You see "Update available" notification in the UI
  3. You manually review and pull the update
  4. This gives you control over the timing of adoption

When to use:

  • ✅ You need control over when updates are pulled
  • ✅ You test artifacts before deploying to production
  • ✅ You manage multiple environments with different release schedules
  • ✅ You have approval workflows for artifact updates

When NOT to use:

  • ❌ You want automatic updates
  • ❌ You're in development mode and want latest always

Example deployment:

# Binding set to snapshot_on_change for a critical system skill
# Upstream releases new versions frequently

Day 1:
  → Artifact pinned to v1.5.0
  → Notification: "Update available (v1.6.0)"
  → You review upstream release notes

Day 3:
  → After testing, you click "Pull Latest"
  → Artifact advances to v1.6.0

3. track_tags

Description: Displays all available Git tags from the repository; you manually select which tag to use.

How it works:

Available Git tags in repository:
  main                    (branch, not tag)
  v2.1.0                  ← You select
  v2.0.5
  v2.0.0
  legacy/v1.9.0
  experimental/feature-x

You can pin to any tag you choose

Tag selection:

  • Lists all Git tags (not releases)
  • Tags can be from any point in the repository history
  • You explicitly choose which tag to use
  • No automatic advancement

When to use:

  • ✅ You want fine-grained control over versions
  • ✅ You use custom tagging schemes (e.g., stable/v1.0, beta/v2.0-beta)
  • ✅ Your repository doesn't use GitHub release tagging
  • ✅ You maintain long-lived release branches

When NOT to use:

  • ❌ You only have GitHub releases (releases are simpler)
  • ❌ You want automatic selection

Example deployment:

# Binding set to track_tags for a custom internal tool
# Repository uses tags: v1.0, v2.0-experimental, v2.0.1-stable

Available tags shown in UI:
  v1.0
  v2.0-experimental
  v2.0.1-stable          ← You select this

Pin to v2.0.1-stable

4. manual_pin

Description: You explicitly specify which release or commit to pin to; SkillMeat never auto-selects.

How it works:

You explicitly specify:
  → "Use v1.2.0 specifically"
  → "Use commit abc123def"

Upstream releases v1.3.0:
  → Your artifact still uses v1.2.0
  → No notification, no update flag
  → You must manually unpin and select new version

Pinning options:

  • Specific release tag (e.g., v2.1.0)
  • Specific Git commit SHA
  • Specific branch (if allowed)

When to use:

  • ✅ You need strict version locking
  • ✅ You maintain a specialized version for your organization
  • ✅ Breaking changes in upstream require code changes you're not ready for
  • ✅ You have a formal release approval process

When NOT to use:

  • ❌ You want to stay relatively current
  • ❌ You use upstream regularly and need updates

Example deployment:

# Binding set to manual_pin for a security-critical component
# You pin to v3.0.0-lts, which has extended support

Pin: v3.0.0-lts

Upstream releases v3.1.0, v3.2.0, v4.0.0:
  → Your artifact still uses v3.0.0-lts
  → No notifications, no auto-pull
  → Stable and controlled

When you're ready (6 months later):
  → Review v3.2.0 (latest v3.x)
  → Test thoroughly
  → Manually unpin and select v3.2.0

Policy Resolution Hierarchy

SkillMeat uses a three-level resolution hierarchy to determine the effective pin policy:

1. Binding-Level Policy (highest priority)
   ├─ If set on artifact binding
   └─ Use this policy

2. Source-Level Default (if binding not set)
   ├─ Marketplace source's default_pin_policy
   └─ Use this policy

3. System Default (if neither above set)
   └─ "snapshot_on_change" (always-safe fallback)

Example:

Binding A:
  - Binding pin_policy: "track_latest_release"  ← Use this (highest priority)
  - Source default: "snapshot_on_change"
  - System default: "snapshot_on_change"
  Result: track_latest_release

Binding B:
  - Binding pin_policy: None
  - Source default: "manual_pin"                 ← Use this
  - System default: "snapshot_on_change"
  Result: manual_pin

Binding C:
  - Binding pin_policy: None
  - Source default: None
  - System default: "snapshot_on_change"        ← Use this (fallback)
  Result: snapshot_on_change

Discover Mode & Webhooks

How Webhooks Work with Pin Policies

Webhooks are the mechanism that detects upstream changes. However, webhooks never force a local sync:

Discovery Flow:

  1. Upstream change occurs (new release published on GitHub)
  2. GitHub webhook fires → SkillMeat API receives notification
  3. Change is registered → update_available flag is set to true
  4. You're notified → Web UI shows "Update available"
  5. You decide → Click to pull update or ignore

Key principle: Webhooks are advisory, not forced. They inform you of upstream activity. The actual sync timing is controlled by your pin policy and your manual actions.

Why Webhooks Don't Force Sync

  • Respects discovery principle — Webhooks set update_available; you control when/if to pull
  • Prevents disruption — Artifacts in production aren't suddenly changed
  • Aligns with all policies — Works consistently across all four pin policies
  • Audit trail — Every update is explicit and traceable

Webhook Subscription Status

When you import an artifact from a GitHub source, SkillMeat automatically attempts to subscribe to webhooks for that source. The subscription has three possible states:

Status Meaning Action
subscribed Webhook is active; upstream changes are detected Normal operation
skipped Webhook subscription was skipped (no setup required) Check source config
failed Webhook subscription failed (permission or config issue) See troubleshooting below

Webhook Requirements:

  • GitHub scope: Your GitHub PAT or app must include admin:repo_hook scope
  • Repository permissions: You must have write access to the repository
  • Source config: Source must have webhook support enabled

Choosing Your Policy

Decision Matrix

Do you want automatic updates?

YES → track_latest_release - Follows latest stable release automatically - Best for rapidly-evolving open-source artifacts - Requires trust in upstream testing

NO → Pick from below...

Do you want some notification of updates?

YES → snapshot_on_change - Get notified of upstream changes via webhook - Manually pull when ready - Good balance of awareness and control

NO (strict control) → Pick from below...

Do you use GitHub releases?

YES → track_tags - Flexible selection from Git tags - Works with custom tagging schemes - Manual selection

NO (need strict locking) → manual_pin - Complete control - Lock to specific version indefinitely - Requires explicit manual updates

By Role

Knowledge Worker (non-technical artifact consumer) - Use: snapshot_on_change (wait for notifications) - Trust: Your team's IT to manage updates

Data Scientist (need stable, tested tools) - Use: track_latest_release (trust upstream) or snapshot_on_change (manual control) - Coordinate with team on update schedule

Software Engineer (building artifacts) - Use: manual_pin (strict control) or track_tags (fine-grained selection) - Test before adoption

DevOps/Platform Engineer (managing artifact infrastructure) - Use: track_latest_release (stay current) with monitoring - Set up alerts for major version changes

Troubleshooting

Issue: "Update available" notification not appearing

Cause: Webhook subscription may have failed or not been set up.

Solution:

  1. Check webhook status in binding details
  2. Verify GitHub PAT has admin:repo_hook scope
  3. Check repository permissions (need write access)
  4. See Webhook Subscription guide for details

Issue: Policy not taking effect

Cause: Wrong policy set, or hierarchy conflict.

Solution:

  1. Check binding-level policy (highest priority)
  2. If not set, check source default policy
  3. Review policy resolution hierarchy above
  4. Verify binding is linked to correct source

Issue: Artifact advanced to version I didn't want

Cause: Policy set to track_latest_release and upstream released new version.

Solution:

  1. Open version history
  2. Restore to previous version
  3. Change policy to manual_pin to prevent future auto-advances
  4. Test before next update