PreviewKit User Guide

Comprehensive reference for configuration and advanced features

New to PreviewKit? Start with the Getting Started Guide for a 5-minute setup walkthrough.

This guide covers authentication options, configuration reference, advanced use cases, and troubleshooting.

Table of Contents

• Prerequisites
• Azure Setup
• Authentication Options
• Workflow Configuration
• Action Inputs Reference
• Action Outputs
• Advanced Configuration
• Troubleshooting

Prerequisites

Azure Resources Required

GitHub Requirements

Azure Setup

For detailed Azure infrastructure setup instructions, see the Getting Started guide.

Once you have your Azure resources configured, choose an authentication method below.

Authentication Options

PreviewKit supports two authentication methods for pulling images from ACR. Choose based on your security requirements:

Option 1: User-Assigned Managed Identity (Recommended)

Best for: Production environments, security-conscious teams

Advantages:

• ✅ No passwords to manage
• ✅ Automatic credential rotation
• ✅ Azure-native security
• ✅ Works for new container apps

Setup:

# Create identity
az identity create --name previewkit-acr-pull --resource-group $RESOURCE_GROUP

# Grant AcrPull permission
IDENTITY_PRINCIPAL=$(az identity show --name previewkit-acr-pull --resource-group $RESOURCE_GROUP --query principalId -o tsv)
ACR_ID=$(az acr show --name $ACR_NAME --query id -o tsv)
az role assignment create --assignee $IDENTITY_PRINCIPAL --role AcrPull --scope $ACR_ID

Workflow usage:

- uses: krav4enkodm/previewkit/action@main
  with:
    azure-registry-server: yourregistry.azurecr.io
    azure-registry-identity: /subscriptions/.../userAssignedIdentities/previewkit-acr-pull

Option 2: Admin Credentials

Best for: Quick setup, testing, simple deployments

Advantages:

• ✅ Simple to configure
• ✅ No identity management required
• ✅ Works immediately

Disadvantages:

• ⚠️ Shared credentials (not per-app)
• ⚠️ Password rotation is manual
• ⚠️ Less secure for production

Setup:

# Enable ACR admin
az acr update --name $ACR_NAME --admin-enabled true

# Get credentials
az acr credential show --name $ACR_NAME

Add to GitHub Secrets:

• AZURE_REGISTRY_USERNAME: ACR admin username
• AZURE_REGISTRY_PASSWORD: ACR admin password

Workflow usage:

- uses: krav4enkodm/previewkit/action@main
  with:
    azure-registry-server: yourregistry.azurecr.io
    azure-registry-username: ${{ secrets.AZURE_REGISTRY_USERNAME }}
    azure-registry-password: ${{ secrets.AZURE_REGISTRY_PASSWORD }}

Workflow Configuration

For a complete workflow example, see Getting Started - Step 3.

Below are the key configuration options and advanced use cases.

Action Inputs Reference

Required Inputs

Cloud Configuration

Azure-Specific Inputs

Container Settings

Optional Settings

Action Outputs

Usage in workflow:

- name: Deploy Preview
  id: preview
  uses: krav4enkodm/previewkit/action@main
  with:
    # ... inputs

- name: Use preview URL
  run: echo "Preview deployed at ${{ steps.preview.outputs.preview-url }}"

Advanced Configuration

Custom Environment Variables

Pass environment variables to your container by configuring them in the Container App directly or through your Dockerfile.

Multiple Services

For multiple services in the same repo, create separate workflows:

# .github/workflows/preview-frontend.yml
- uses: krav4enkodm/previewkit/action@main
  with:
    service-name: frontend
    port: 3000

# .github/workflows/preview-backend.yml
- uses: krav4enkodm/previewkit/action@main
  with:
    service-name: backend
    port: 8080

Preview Naming

Preview environments are named deterministically:

<service-name>-pr-<number>-<sha-prefix>

Example: my-frontend-pr-42-a1b2c3d

This ensures:

• Unique names per PR
• No collisions between services
• Easy identification in Azure portal

Troubleshooting

Common Issues

"Environment not found"

Cause: Container Apps Environment doesn't exist or wrong name

Fix:

# List available environments
az containerapp env list --resource-group $RESOURCE_GROUP --query "[].name" -o tsv

"Failed to pull image" / ACR authentication error

Cause: Missing or incorrect ACR credentials

Fix:

1. If using managed identity, verify role assignment:
   bashCopy

   az role assignment list --assignee $IDENTITY_PRINCIPAL --scope $ACR_ID
   

2. If using admin credentials, verify they're correct:
   bashCopy

   az acr credential show --name $ACR_NAME
   

"OIDC authentication failed"

Cause: Federated credential not configured for pull requests

Fix:

# Check existing credentials
az ad app federated-credential list --id $APP_OBJECT_ID

# Create credential for pull_request
az ad app federated-credential create \
    --id $APP_OBJECT_ID \
    --parameters '{
        "name": "github-pr",
        "issuer": "https://token.actions.githubusercontent.com",
        "subject": "repo:YOUR_ORG/YOUR_REPO:pull_request",
        "audiences": ["api://AzureADTokenExchange"]
    }'

"Identity operation failed" / Location mismatch

Cause: Stale managed identity from previous failed deployment

Fix:

# Delete stale identity
az identity delete --name <identity-name> --resource-group $RESOURCE_GROUP

# Delete stale container app
az containerapp delete --name <app-name> --resource-group $RESOURCE_GROUP --yes

Debug Mode

For detailed logs, check the GitHub Actions logs:

1. Go to Actions tab in your repository
2. Click on the failed run
3. Expand the "Deploy Preview" step

Support

• Issues: GitHub Issues
• Documentation: docs/

What's Next

• Just getting started? See the Getting Started Guide for a complete setup walkthrough
• Roadmap: PreviewKit is actively developed with upcoming features including AWS App Runner, GCP Cloud Run, preview dashboard, and cost visibility