GitHub Actions Deployment

Automatically build and publish your scenario whenever you push changes to GitHub.

What is GitHub Actions?

GitHub Actions is a free automation service that can automatically build and publish your scenario every time you push changes to your repository. This means you don't have to manually run npm run publish:scenario - it happens automatically!

Existing Workflow Files

The template repository already includes two workflow files:

• .github/workflows/publish-live.yml - Deploys to production when you push to main branch
• .github/workflows/publish-uat.yml - Deploys to staging when you push to develop branch

You just need to configure the GitHub Secrets and the workflows will work automatically!

Prerequisites

Before the workflows can run, you need:

1. Your scenario in a GitHub repository (created using the template)
2. Your Scenario ID from the Scenarios Management Page
3. Your API Key from the Manage Passport Tokens Page

Setting Up GitHub Secrets

GitHub Secrets are a secure way to store sensitive information like API keys. Your secrets are encrypted and never exposed in your code.

Step 1: Go to Repository Settings

1. Open your scenario repository on GitHub
2. Click Settings (top menu)
3. In the left sidebar, click Secrets and variables
4. Click Actions

Step 2: Add Your Secrets

The template includes workflows for both Live (production) and Staging environments. You need to add secrets for the environment(s) you want to use.

For Live/Production Deployment

Add these three secrets:

1. Add LIVE_BASE_URL

1. Click New repository secret
2. Name: LIVE_BASE_URL
3. Secret: https://leftunread.app
4. Click Add secret

2. Add LIVE_SCENARIO_ID

1. Click New repository secret
2. Name: LIVE_SCENARIO_ID
3. Secret: Paste your scenario UUID (copied from the URL after creating your scenario)
4. Click Add secret

3. Add LIVE_API_KEY

1. Click New repository secret
2. Name: LIVE_API_KEY
3. Secret: Paste your API key from the tokens page
4. Click Add secret

4. Add GH_PACKAGES_TOKEN

1. Click New repository secret
2. Name: GH_PACKAGES_TOKEN
3. Secret: Paste your GitHub Personal Access Token (PAT) with read:packages permission
   • Use the same token you used in your local .npmrc file
   • Create one at https://github.com/settings/tokens if needed
4. Click Add secret

For Staging Deployment (Optional)

If you want to use the staging environment for testing before going live, add these secrets:

1. Add UAT_BASE_URL

1. Click New repository secret
2. Name: UAT_BASE_URL
3. Secret: https://staging.leftunread.app
4. Click Add secret

2. Add UAT_SCENARIO_ID

1. Click New repository secret
2. Name: UAT_SCENARIO_ID
3. Secret: Your staging scenario ID
4. Click Add secret

3. Add UAT_API_KEY

1. Click New repository secret
2. Name: UAT_API_KEY
3. Secret: Your staging API key
4. Click Add secret

4. Add GH_PACKAGES_TOKEN (If not already added for Live)

1. Click New repository secret
2. Name: GH_PACKAGES_TOKEN
3. Secret: Paste your GitHub Personal Access Token (PAT) with read:packages permission
   • Use the same token you used in your local .npmrc file
   • Create one at https://github.com/settings/tokens if needed
4. Click Add secret

Token Reuse

You only need to add GH_PACKAGES_TOKEN once - it's used for both Live and Staging deployments since it's for accessing npm packages, not environment-specific.

Just Getting Started?

If you're just starting out, you only need to set up the LIVE secrets. The staging environment is optional and mainly useful for testing changes before they go to production.

Keep Secrets Safe

Never commit your API key or Scenario ID directly in your code! Always use GitHub Secrets for sensitive information.

Understanding the Workflow Files

The template already includes workflow files, so you don't need to create them! Let's understand what they do:

Live Deployment (.github/workflows/publish-live.yml)

This workflow automatically deploys to production:

name: Publish scenario (Live)

on:
  push:
    branches: [ 'main' ]  # Triggers when you push to main branch

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Publish scenario to Live
        env:
          BASE_URL: ${{ secrets.LIVE_BASE_URL }}
          API_KEY: ${{ secrets.LIVE_API_KEY }}
          SCENARIO_ID: ${{ secrets.LIVE_SCENARIO_ID }}
        run: npm run publish:scenario

What it does:

1. Triggers when you push to the main branch
2. Checks out your code
3. Installs Node.js and dependencies
4. Runs npm run publish:scenario with your LIVE secrets

Staging Deployment (.github/workflows/publish-uat.yml)

This workflow deploys to a testing environment:

name: Publish scenario (Staging)

on:
  push:
    branches: [ 'develop' ]  # Triggers when you push to develop branch

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Publish scenario to Staging
        env:
          BASE_URL: ${{ secrets.UAT_BASE_URL }}
          API_KEY: ${{ secrets.UAT_API_KEY }}
          SCENARIO_ID: ${{ secrets.UAT_SCENARIO_ID }}
        run: npm run publish:scenario

What it does:

1. Triggers when you push to the develop branch
2. Same steps as Live, but uses Staging secrets

Workflow Already Exists!

The workflow files are already in your repository from the template. You don't need to create them - just add the GitHub Secrets and they'll work automatically!

How It Works

Once you've added the GitHub Secrets, here's what happens automatically:

Deploying to Production (Live)

1. You make changes - Edit your Ink files, contacts, or assets
2. You commit and push to main - git push origin main
3. GitHub Actions triggers - The publish-live.yml workflow starts
4. Publishes to server - Runs npm run publish:scenario using your LIVE secrets
5. Scenario is live - Your updated scenario is automatically deployed to production!

Deploying to Staging

1. You make changes - Edit your Ink files, contacts, or assets
2. You commit and push to develop - git push origin develop
3. GitHub Actions triggers - The publish-uat.yml workflow starts
4. Publishes to staging - Runs npm run publish:scenario using your Staging secrets
5. Test your scenario - Review changes in the staging environment before going live

Recommended Workflow

1. Make changes and push to develop branch
2. Test your scenario in the staging environment
3. When ready, merge develop into main
4. Automatically deploys to production!

Viewing Workflow Status

Check if it's Running

1. Go to your repository on GitHub
2. Click the Actions tab
3. You'll see a list of workflow runs
4. Click on a run to see detailed logs

Understanding Status Icons

• 🟡 Yellow dot - Workflow is currently running
• ✅ Green checkmark - Workflow completed successfully
• ❌ Red X - Workflow failed (check the logs)

Troubleshooting

Workflow Failed

If your workflow fails:

1. Click on the failed workflow run
2. Click on the "deploy" job
3. Expand the failed step to see error details
4. Common issues:
   • Invalid API key - Check your API_KEY secret is correct
   • Scenario not found - Verify your scenario ID secret (SCENARIO_ID / LIVE_SCENARIO_ID)
   • Build errors - Fix Ink syntax errors in your scenario

Secrets Not Working

If secrets aren't being used:

1. Verify secret names are exactly: BASE_URL, SCENARIO_ID, API_KEY
2. Check they're in Repository secrets (not Environment secrets)
3. Make sure you pushed the workflow file to the repository

Workflow Not Triggering

If the workflow doesn't run when you push:

1. Check the workflow file is in .github/workflows/deploy.yml
2. Verify you're pushing to the correct branch (default is main)
3. Check the Actions tab isn't disabled in repository settings

Advanced Configuration

Deploy Only on Specific Branches

To deploy only when pushing to a specific branch:

on:
  push:
    branches:
      - production  # Only deploy from production branch

Deploy on Pull Request Merge

To deploy when a pull request is merged:

on:
  pull_request:
    types:
      - closed
    branches:
      - main

jobs:
  deploy:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    # ... rest of the job

Manual Deployment

To allow manual triggering of deployments:

name: Build and Deploy Scenario

on:
  push:
    branches:
      - main
  workflow_dispatch:  # Adds manual trigger button

jobs:
  deploy:
    # ... rest of workflow

Then you can manually trigger from the Actions tab → Select workflow → Run workflow.

Build on Push, Deploy Manually

If you want to build automatically but deploy manually:

name: Build Scenario

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build scenario
        run: npm run build:scenario
      
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: scenario-build
          path: dist/scenario-build.zip

Then create a separate workflow for deployment that you trigger manually.

Best Practices

Use Branch Protection

1. Create a development branch for testing
2. Only merge to main when ready to deploy
3. Set up branch protection rules to require reviews

Test Before Deploying

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install
      - run: npm run build:scenario
  
  deploy:
    needs: test  # Only deploy if test passes
    runs-on: ubuntu-latest
    # ... deployment steps

Add Notifications

Get notified when deployments succeed or fail by adding a notification step:

      - name: Notify on success
        if: success()
        run: echo "✅ Scenario deployed successfully!"
      
      - name: Notify on failure
        if: failure()
        run: echo "❌ Deployment failed!"

Security Notes

Important Security Practices

• ✅ Always use GitHub Secrets for API keys and Scenario IDs
• ✅ Never commit .env files to your repository
• ❌ Never hardcode API keys in workflow files
• ✅ Rotate API keys periodically for security
• ✅ Use minimal permissions - only give the API key what it needs

Benefits of Automated Deployment

• ⚡ Faster updates - No manual build and publish steps
• 🔒 More secure - Secrets stored safely in GitHub
• 📝 Better tracking - See deployment history in Actions tab
• 🤝 Team collaboration - Multiple people can contribute without sharing API keys
• ✅ Consistent builds - Same build process every time
• 🔄 Easy rollbacks - Redeploy previous commits if needed

Quick Setup Summary

Here's everything you need to do to enable automatic deployment:

1. Add GitHub Secrets (in your repository Settings → Secrets and variables → Actions):

   • LIVE_BASE_URL = https://leftunread.app
   • LIVE_SCENARIO_ID = Your scenario UUID
   • LIVE_API_KEY = Your API key
   • GH_PACKAGES_TOKEN = Your GitHub Personal Access Token (PAT) with read:packages permission

2. Push to main branch:

   git add .
   git commit -m "Update scenario"
   git push origin main

3. Watch it deploy - Go to the Actions tab to see the workflow run!

That's it! The workflow files are already in the template, so once you add the secrets, everything works automatically.

Next Steps

• Learn about Build and Publish for manual deployment
• Understand Project Structure for organizing your files
• Check out Ink Scripting to improve your scenarios