Choosing an Asset Versioning Strategy in ShotGrid: Built‑in Versions vs Git LFS

Decision Context

When a studio adopts ShotGrid to track assets, a common engineering decision is how to store and version large binary files. ShotGrid offers a native Version entity that can hold a copy of the file, while many teams prefer to keep binaries in Git Large File Storage (LFS) and reference them from ShotGrid. This guide helps you decide which strategy fits your workflow, constraints, and budget.

Key Constraints

• File Size: Typical ShotGrid Version uploads are limited to < 100 MB. Larger assets (e.g., high‑resolution textures, rendered frames) may exceed this cap.
• Storage Cost & Quota: ShotGrid’s database/file store incurs per‑GB charges and may have quota limits for large studios.
• Audit & Backup: Built‑in versions benefit from ShotGrid’s backup and disaster‑recovery. Git LFS relies on external hosting.
• Workflow Familiarity: Teams that already use Git for code may prefer to extend that workflow to assets.
• Security & Access: ShotGrid’s role‑based controls are applied automatically; Git LFS requires separate permission configuration.
• Performance: Uploading a Version via API is lightweight; pushing to Git LFS can be bandwidth‑heavy.

Supported Options

Feature	ShotGrid Version Entity	Git LFS Integration
Storage Location	ShotGrid database/file store	External Git repo (e.g., GitHub, GitLab, Gitea)
Maximum File Size	~100 MB (configurable a bit higher)	Unlimited (subject to repo host limits)
Version Metadata	Automatically captured (asset, tags, user, date)	Stored in a custom field (URL or SHA)
Backup & Recovery	ShotGrid’s built‑in backup	Depends on repo host’s policy
Access Control	ShotGrid roles & permissions	Git host’s repo permissions + token management
Workflow Integration	Web UI & API only	Git commands, pull requests, CI pipelines
Cost	ShotGrid storage fees	Repo hosting fees + possible bandwidth charges
Performance	Fast API upload, small payloads	Large file transfer over Git LFS, slower
Audit Trail	Full audit in ShotGrid logs	Git commit history + ShotGrid record
Complexity	Minimal – one API call	Requires Git setup, token handling, custom scripts

Trade‑Off Analysis

When Built‑in Versions Win

• Small to medium assets (<100 MB) that need to stay tightly coupled with ShotGrid.
• Teams that want a single point of truth and minimal external tooling.
• Projects where storage cost is a primary concern and the volume of large binaries is low.
• Scenarios that rely heavily on ShotGrid’s backup and role‑based access.

When Git LFS Wins

• Large assets that regularly exceed ShotGrid’s upload limits.
• Workflows that already use Git for code and want to unify asset and code review.
• Teams that need efficient delta compression and branching for asset variations.
• Projects that prefer to host backups on a dedicated Git host with its own retention policies.

Concrete Implementation Paths

1. Using ShotGrid’s Built‑in Version Entity

1. Prerequisites: API key with write permission for Version entity, access to ShotGrid instance.
2. API Call – Create a Version and attach a file:

   POST https://{sg_host}/api/v1/version
   Headers: {
     "Authorization": "Bearer {API_KEY}",
     "Content-Type": "application/json"
   }
   Body: {
     "project": {"id": 123},
     "entity": {"type": "Asset", "id": 456},
     "name": "Render v02",
     "description": "Second render of frame 0010",
     "file": {
       "fileName": "frame_0010.png",
       "url": "https://example.com/path/to/frame_0010.png"
     }
   }

3. Verification: Open the asset in the ShotGrid web UI and confirm the new Version appears under the Versions tab.

2. Integrating Git LFS with ShotGrid

1. Prerequisites: Git host with LFS support, SSH key or personal access token (PAT) with repo access, ShotGrid API key, custom field (e.g., git_lfs_url) on the Asset entity.
2. Push to Git LFS – From a local clone:

   # Configure LFS
   git lfs install
   
   # Add asset
   cp /path/to/large_asset.tif .
   
   git add large_asset.tif
   
   git commit -m "Add asset v1"
   
   git push origin main
   

3. Store reference in ShotGrid – Use the API to update the custom field:

   PATCH https://{sg_host}/api/v1/asset/456
   Headers: {
     "Authorization": "Bearer {API_KEY}",
     "Content-Type": "application/json"
   }
   Body: {
     "git_lfs_url": "https://git.example.com/repo.git/blob/main/large_asset.tif"
   }
   

4. Retrieval: In the ShotGrid UI, a custom field widget can display the URL. For automated pipelines, use the API to fetch the URL and run git lfs pull to download the file.
5. Verification: Use the ShotGrid API to read the git_lfs_url field and confirm it points to a valid LFS object. Run git lfs ls-files locally to ensure the file is present.

Validation Checklist

• Built‑in Version: GET /api/v1/version?asset=456 returns the newly created entity and file URL.
• Git LFS Reference: GET /api/v1/asset/456 returns git_lfs_url that resolves to a Git LFS blob.
• Storage Cost: Query ShotGrid usage metrics (GET /api/v1/usage) and compare to Git host repository statistics.
• Backup Test: Simulate a backup restore on ShotGrid and verify the Version entity is intact.
• Security Test: Attempt to access the Git LFS URL from an unauthorized user and confirm access is denied.

Limitations & Migration Considerations

• Built‑in Versions scale poorly for >10,000 large binaries; plan for quota monitoring.
• Git LFS requires careful credential handling—store tokens in a secure vault, not in plain text fields.
• Synchronizing metadata (tags, status) between ShotGrid and Git is manual unless a dedicated sync script is written.
• Switching strategies may duplicate assets; design a migration script that copies files and updates references.
• External Git host bandwidth limits can incur unexpected costs; monitor usage.

Practical Takeaway

For most studios, use ShotGrid’s built‑in Version entity for small to medium assets to keep everything in one place and reduce complexity. Reserve Git LFS for large binaries, high‑frequency updates, or when you want to leverage Git’s branching and review capabilities. Tailor the choice to your file sizes, budget, and existing toolchain.