License Management

Everything you need to know about PreviewKit licenses, tiers, and usage limits

Table of Contents

• Overview
• Getting a License Key
• Adding Your License Key
• Tier Comparison
• Understanding Seat-Based Licensing
• Usage Limits Explained
• Upgrading or Downgrading
• License Troubleshooting

Overview

PreviewKit uses a seat-based licensing model to provide fair, predictable pricing based on team size. You only pay for the people who actually use PreviewKit, measured by who triggers deployments.

What is a License Key?

A license key is a unique identifier that unlocks PreviewKit features for your organization:

• Format: pk_live_Xt7kP9mN2qR5vL8wJ4xC6yB3zA
• Storage: Keys are stored securely as GitHub repository secrets
• Security: We never store your key in plain text - only a cryptographic hash

Do I Need a License Key?

Getting a License Key

Free Tier

No license key needed! Simply install the GitHub Action and start deploying. You'll automatically get:

• 3 seats (unique deployers per month)
• 3 concurrent preview environments
• 50 deployments per month
• 2 repositories

Paid Tiers

To upgrade from free tier:

1. Visit: previewkit.dev/pricing
2. Select your tier: Team, Business, or Enterprise
3. Complete checkout via Stripe
4. Receive your license key via email within minutes

Email delivery includes:

• Your license key (pk_live_...)
• Setup instructions
• Tier limits and usage guidelines

Adding Your License Key

Once you have a license key, add it to your GitHub repository as a secret.

Step 1: Open GitHub Secrets Settings

1. Go to your repository on GitHub
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret

Step 2: Add the Secret

• Name: PREVIEWKIT_LICENSE_KEY
• Value: Your full license key (e.g., pk_live_Xt7kP9mN2qR5vL8wJ4xC6yB3zA)
• Click Add secret

Step 3: Update Your Workflow

Add the license key to your PreviewKit workflow:

- name: Deploy Preview
  uses: krav4enkodm/previewkit/action@main
  with:
    license-key: ${{ secrets.PREVIEWKIT_LICENSE_KEY }} # Add this line
    service-name: my-app
    port: 3000
    # ... other inputs

Step 4: Verify

Create a new PR to trigger a deployment. Check the workflow logs for:

✓ License validated: team tier
✓ Seats: 5/10 (5 seats remaining)
✓ Concurrent previews: 2/10

Tier Comparison

Understand the limits for each tier:

What Happens When I Hit a Limit?

When you reach a limit, deployments will fail with a clear error message:

❌ Seat limit reached (11/10). Upgrade to add more users.

Your existing previews continue running - only new deployments are blocked until you:

• Upgrade to a higher tier
• Wait for the monthly/rolling window to reset
• Remove inactive users

Understanding Seat-Based Licensing

PreviewKit counts seats based on who actually deploys, not your total team size.

How Seats Are Counted

A "seat" is one unique GitHub user who triggers a preview deployment within a 30-day rolling window.

Example:

Who Counts as a Seat?

✅ Counted:

• Any GitHub user who opens a PR
• Any user who pushes to a PR branch
• Human users who trigger deployments

❌ Not counted:

• Bot accounts (dependabot, renovate, etc.)
• Users who only review or comment (but don't push)
• Closed/merged PRs (after cleanup)

Rolling Window Explained

The 30-day window is rolling, not calendar-based:

• Not: "January 1 - January 31"
• Instead: "Last 30 days from today"

This means seats naturally drop off as users become inactive, without manual management.

Checking Your Seat Usage

Currently, seat usage is shown in workflow logs:

- name: Deploy Preview
  uses: krav4enkodm/previewkit/action@main
  # ... workflow will output:
  # ✓ Seats: 7/10 (3 seats remaining)

Coming soon: Dashboard to view:

• Current seat count
• Which users are consuming seats
• Historical seat usage
• Projected seat usage

Usage Limits Explained

Concurrent Previews

What it is: Maximum number of preview environments running at the same time.

Example: With Team tier (10 concurrent):

• You can have 10 PRs with active previews simultaneously
• Opening an 11th PR will fail until you close/merge an existing PR
• Merged PRs automatically clean up within minutes

Best practice: Enable auto-cleanup on PR close to free up slots.

Monthly Deployments

What it is: Total number of preview deployments per calendar month (resets on the 1st).

What counts:

• ✅ Initial PR deployment
• ✅ Every push to PR branch (re-deploys)
• ❌ PR cleanup/destruction

Example: With Team tier (500/month):

• 50 PRs × 10 pushes each = 500 deployments
• Month resets on the 1st, counter goes back to 0

Repositories

What it is: Number of different repositories that can use PreviewKit.

Example: With Free tier (2 repos):

• myorg/frontend - ✅ Allowed
• myorg/backend - ✅ Allowed
• myorg/mobile - ❌ Blocked (upgrade needed)

Per-repo licensing: Each repo needs the license key in its secrets.

Upgrading or Downgrading

Upgrading Your Tier

To upgrade:

1. Visit previewkit.dev/pricing
2. Select your new tier
3. Complete checkout
4. Receive a new license key via email
5. Update PREVIEWKIT_LICENSE_KEY in GitHub secrets
6. New limits apply immediately

Prorated billing: You'll only pay the difference for the current month.

Downgrading Your Tier

To downgrade:

1. Email support@previewkit.dev with:
   • Current license key (first 10 characters)
   • Desired tier
   • Effective date
2. Receive new license key
3. Update GitHub secret
4. Lower limits apply on next billing cycle

What happens if I exceed limits after downgrading?

Example: Downgrade from Business (25 concurrent) to Team (10 concurrent), but have 15 active previews:

• Existing 15 previews keep running
• New deployments blocked until count drops below 10
• Close/merge PRs to free up slots

Canceling Your License

1. Remove PREVIEWKIT_LICENSE_KEY from GitHub secrets
2. You'll fall back to free tier immediately
3. Free tier limits apply (3 seats, 3 concurrent, 50/month, 2 repos)
4. Email support@previewkit.dev to stop billing

License Troubleshooting

"Invalid license key format"

Cause: License key is malformed or incomplete.

Fix:

1. Check the key in GitHub secrets
2. Ensure you copied the entire key including pk_live_ prefix
3. No extra spaces or line breaks
4. Re-copy from the email if needed

Valid format example: pk_live_Xt7kP9mN2qR5vL8wJ4xC6yB3zA

"License key not found"

Cause: The license key doesn't exist in our database.

Fix:

1. Verify you received the key via email after purchase
2. Check spam/junk folders
3. Ensure you're using the latest key (if you upgraded)
4. Contact support@previewkit.dev with your order number

"License is inactive" or "License is revoked"

Cause: License has been disabled due to:

• Payment failure
• Subscription cancellation
• Policy violation

Fix:

1. Check your payment method in Stripe
2. Update billing information if needed
3. Contact support@previewkit.dev if payment is current

"License has expired"

Cause: License passed its expiration date.

Fix:

• Annual licenses: Renew at previewkit.dev/pricing
• Monthly subscriptions: Check billing status
• Trial licenses: Upgrade to paid tier

"Seat limit reached (11/10)"

Cause: More unique users deployed in the last 30 days than your tier allows.

Fix Options:

Option 1: Upgrade tier

• Team → Business (10 → 40 seats)
• Business → Enterprise (unlimited)

Option 2: Wait for rolloff

• Seats automatically drop after 30 days of inactivity
• Check which users deployed recently
• Ask inactive team members to hold off

Option 3: Remove users

• If a user no longer needs preview access, they can avoid deploying
• Note: You can't manually remove seats - they drop off after 30 days

"Concurrent preview limit reached (3/3)"

Cause: Too many PRs with active previews at the same time.

Fix:

1. Close old PRs - Previews auto-cleanup within 5 minutes
2. Merge ready PRs - Frees up slots immediately
3. Upgrade tier - Free → Team (3 → 10 concurrent)

Check active previews in Azure Portal:

az containerapp list --resource-group YOUR_RESOURCE_GROUP --query "[].name"

"Monthly deploy limit reached (50/50)"

Cause: Exceeded deployments for the current calendar month.

Fix:

• Wait until next month - Limit resets on the 1st
• Upgrade tier - Free (50) → Team (500) → Business (2,000)
• Reduce re-deploys - Batch commits before pushing

When does it reset? First day of next month at 00:00 UTC.

"Repository limit reached (2/2)"

Cause: Too many repositories using PreviewKit for your tier.

Fix:

1. Remove PreviewKit from unused repos - Delete the workflow file
2. Upgrade tier - Free (2) → Team (10) → Business (50)
3. Consolidate repos - Use monorepo if possible

License Key Security

Best Practices

✅ Do:

• Store keys in GitHub Secrets (encrypted at rest)
• Use separate keys for staging/production if needed
• Rotate keys if compromised

❌ Don't:

• Commit keys to your repository
• Share keys publicly (GitHub issues, Slack, etc.)
• Use production keys in public repos

If Your Key is Compromised

1. Immediately: Remove the key from GitHub secrets
2. Email: support@previewkit.dev with "Key Compromised" in subject
3. We'll: Revoke the old key and issue a new one
4. Update: Add new key to GitHub secrets

Usage Visibility

Current Methods

Workflow logs show:

✓ License: team tier
✓ Seats: 7/10 (3 remaining)
✓ Concurrent: 4/10
✓ Monthly: 125/500
✓ Repositories: 3/10

Coming Soon: Dashboard

We're building a usage dashboard where you'll see:

• Real-time seat count with user breakdown
• Active preview environments
• Monthly deployment trends
• Usage forecasting
• Billing estimates

Want early access? Email support@previewkit.dev

Need Help?

Support Channels

• Free tier: GitHub Issues
• Paid tiers: Support form
• Enterprise: Direct email to your account manager

Common Questions

Q: Can I share a license key across multiple organizations? A: No. Each GitHub organization needs its own license. Contact sales for multi-org discounts.

Q: Do I need a license key for private repos? A: No. Free tier works for both public and private repos. License unlocks higher limits.

Q: What happens if my payment fails? A: You get a 7-day grace period, then the license is marked inactive. Update billing to restore access.

Q: Can I transfer a license to another organization? A: Yes, email support@previewkit.dev with both organization names and we'll handle the transfer.

Ready to upgrade? Visit previewkit.dev/pricing

Questions? Email support@previewkit.dev