Storage Options
Every Knapsack workspace stores content in one of two places: Knapsack Database or your Git repository. Database storage gets you started instantly. Git storage gives you version control, CI/CD integration, and live component previews.
Which Should You Choose?
Choose Knapsack Database when you want to:
- Start documenting immediately—no deployment or Git setup required
- Keep your review workflow entirely in Knapsack
- Try Knapsack before committing to full Git integration
Choose Git Repository when you want to:
- Full version history and diffs for all content changes
- Live component previews showing your actual code
- Pull Request workflows with your existing review process
- CI/CD integration and content stored locally in your repo
Not sure which to pick? Start with Database storage. You can migrate to Git later without losing any content.
What’s Stored Where?
Understanding where your content lives helps you plan your workflow and know what to expect during migration.
Content you control
Your storage choice (Database or Git) determines where this content lives:
Content Knapsack manages
These stay on Knapsack Cloud regardless of your storage choice—you don’t need to manage or migrate them.
Content in your codebase
These always live in your repository, independent of your storage choice.
Knapsack reads from your codebase to discover components and render live previews. Your storage choice only affects where documentation content lives—not your code.
Live previews require a hosted design system. Your components (Button, Card, Modal) need to be running somewhere Knapsack can reach—cloud-hosted environments like Heroku, self-hosted, or custom domain. Database storage is for teams who want to start documenting before setting that up.
How Branching Works
Migrating to Git
Already using Knapsack Database and want to switch to Git? Migration preserves all your content.
Migration is one-way. Once you migrate to Git, you can’t switch back to Database storage.
Requirements
Before you begin, make sure you have:
- Admin permissions in your Knapsack workspace
- A Git provider account (GitHub, GitLab, Bitbucket, or Azure DevOps)
- A deployment URL where your design system is hosted—Knapsack’s cloud services need network access to this URL
Step 1: Request migration access
Contact Knapsack support to enable migration for your workspace. Once enabled, a Configuration page appears under Settings → Administration.
Step 2: Configure your connections
Go to Settings → Configuration and add:
- Your Deployment URL — where your design system is hosted
- Your Git Provider — connect to GitHub, GitLab, Bitbucket, or Azure DevOps
Click Save Changes to validate both connections.
Step 3: Prepare for migration
- Notify your team about the upcoming content freeze
- Publish or delete all open branches — the Start Migration button stays locked until all branches are closed
Step 4: Start migration
Click Start Migration in Settings → Configuration. Knapsack will:
- Create a branch in your repository containing all your content
- Open a Pull Request for you to review
- Freeze publishing until migration is complete
What you’ll see: A PR containing YAML and JSON files for your pages, tokens, navigation, and settings.
Step 5: Complete migration
- Review and merge the PR in your Git provider
- Wait for your deployment to update with the new content
- Contact Knapsack support to lift the publishing freeze
- Notify your team they can resume editing
What gets migrated: Pages, tokens, navigation, blocks, demos, tabs, block collections, asset sets, and settings all move to your repository.
FAQ
Can I switch from Git back to Database?
No. Migration is one-way—once your content is in Git, it stays there. If you have a specific need to revert, contact Knapsack support to discuss options.
Will I lose content during migration?
No. Migration exports all your content to a Pull Request in your repository. Uploaded files (images, PDFs) remain on Knapsack’s CDN and continue working after migration.
Why don’t live component previews work with Database storage?
Live component previews require Git storage mode. When content is stored in the database, Knapsack doesn’t connect to your deployment—even if you have one configured. This is by design: Database storage is for workspaces that want to start quickly without deployment setup.
Can I use Database storage for documentation only (no code)?
Yes. Database storage is ideal for design system documentation, tokens, guidelines, and pattern definitions without connecting to code components.
What happens to my open branches during migration?
You must publish or delete all open branches before migration can start. Once all branches are closed, workspace admins can click Start Migration to begin the process.
How long does migration take?
The migration PR is created immediately. The total timeline depends on:
- How long your team takes to review the PR
- Your deployment pipeline speed (typically 2–10 minutes)
- Any merge conflicts that need resolution
What if the migration PR has conflicts?
Resolve conflicts in your Git provider (GitHub/GitLab), then merge. This typically happens if your repository already has Knapsack content files.
Do I need to re-upload images after migration?
No. Uploaded files stay on Knapsack’s CDN and continue working after migration. Only the content structure (pages, tokens, etc.) moves to Git.
Troubleshooting
Migration button is disabled
You have open branches. Publish or delete all branches with “Draft” or “Review Requested” status before migrating.
Can’t find the Configuration page
The Configuration page only appears after Knapsack support enables migration for your workspace. Contact support if you don’t see it under Settings → Administration.
Git provider connection fails
Check that your Git credentials have write access to the repository. For GitHub, ensure your token has repo scope. For GitLab, ensure api and write_repository scopes.
Deployment validation fails
Verify your deployment URL is accessible to Knapsack’s cloud services and running a Knapsack App Client. The URL should return a valid response when visited in a browser.
Live previews not working after migration
Verify your deployment URL is accessible to Knapsack’s cloud services and running a Knapsack App Client. For firewall-protected deployments, ensure Knapsack’s static IP is whitelisted.