Tutorial 4: Creating GitHub Actions

By now, you've discovered that Kantan CMS has powerful GitHub integration features. In this tutorial, we'll guide you through creating automated GitHub Actions workflows that will streamline your development process and automatically deploy your website whenever you make changes to your code or content.

Prerequisites

Before starting this tutorial, ensure you have:

• Your project uploaded to GitHub (from previous tutorials)
• The MCP setup from Tutorial 3
• The build.sh script created in Tutorial 3
• Administrative access to your GitHub repository

Setting Up GitHub Integration

Step 1: Authorize Kantan CMS App

1. Visit https://github.com/apps/kantan-cms-app
2. Click "Install" or "Configure"
3. Select the repository you want to integrate with Kantan CMS
4. Grant the necessary permissions to allow Kantan CMS to:
   • Access your repository
   • Trigger builds and deployments
   • Read repository contents
   • Create deployment statuses

This authorization allows Kantan CMS to automatically trigger builds and deployments directly from your GitHub repository.

Generating GitHub Actions Workflow

Step 1: Use MCP to Create Workflow

Open your AI editor with MCP enabled and use the following prompt to generate a GitHub Actions workflow:

Generate a GitHub Actions workflow that can be used to upload website to CMS.
Use `build.sh` to upload your website.

The workflow should:
- Trigger on push to main branch
- Set up the necessary environment
- Run the build script
- Handle any dependencies
- Provide clear logging and error handling

Step 2: Review Generated Workflow

The AI will generate a workflow file, typically named something like .github/workflows/deploy.yml. Make note of:

• File name and location
• Trigger conditions (when the workflow runs)
• Environment variables that need to be set
• Dependencies and setup steps

Step 3: Customize Workflow (if needed)

Review the generated workflow and customize it for your specific needs:

• Adjust trigger conditions (e.g., specific branches, pull requests)
• Add environment-specific configurations
• Include additional testing or validation steps
• Configure notification settings

Configuring Kantan CMS Integration

Step 1: Set Up GitHub Integration in CMS

1. Go to Settings > GitHub Integration in your Kantan CMS dashboard
2. Enter your repository information:
   • Repository URL: Your GitHub repository URL
   • Branch: The branch you want to deploy from (usually main or master)
   • Build Command: Reference to your build.sh script
3. Save the configuration

Step 2: Configure Environment Variables

In your GitHub repository settings:

1. Go to Settings > Secrets and variables > Actions
2. Add the following repository secrets:
   • CMS_API_KEY: Your Kantan CMS API key
   • PROJECT_ID: Your Kantan CMS project ID
   • Any other environment variables your build script requires

Deploying with GitHub Actions

Step 1: Trigger Initial Deployment

1. Navigate to Hosting > Build in Kantan CMS
2. Select "Build With GitHub"
3. Enter the required information:
   • Repository details
   • Branch to deploy
   • Any additional configuration
4. Click "Trigger Deployment"

Step 2: Monitor Deployment

1. Check the Actions tab in your GitHub repository
2. Monitor the workflow execution
3. Review logs for any errors or issues
4. Verify that the build completes successfully

Publishing Your Website

Step 1: Preview the Result

1. Once the GitHub Action completes successfully
2. Go to Hosting > Preview in Kantan CMS
3. Review your deployed website
4. Check that all content is displaying correctly
5. Test forms and interactive elements

Step 2: Deploy to Production

1. If you're satisfied with the preview, click "Deploy"
2. Your website will be deployed to your live domain
3. The deployment will be accessible via your custom domain configured in Tutorial 1

Automated Workflow Benefits

With GitHub Actions now configured, you'll enjoy several benefits:

Continuous Integration

• Automatic builds when you push code changes
• Content updates trigger automatic deployments
• Consistent deployment process across all changes

Version Control

• Track all changes to your website through Git
• Rollback capabilities if issues arise
• Collaborative development with team members

Efficient Development

• No manual upload steps required
• Automated testing can be integrated
• Deployment notifications keep you informed

Workflow Customization Examples

Multiple Environment Deployment

# Deploy to staging on develop branch
# Deploy to production on main branch
on:
  push:
    branches: [main, develop]

Conditional Deployments

# Only deploy if specific files changed
paths:
  - 'src/**'
  - 'content/**'
  - 'build.sh'

Advanced Build Steps

# Include testing before deployment
- name: Run tests
  run: npm test
  
- name: Build and deploy
  run: ./build.sh

Troubleshooting Common Issues

Workflow Fails to Start

• Check repository permissions for Kantan CMS app
• Verify workflow file syntax
• Ensure all required secrets are configured

Build Script Errors

• Review GitHub Actions logs
• Check that all dependencies are available in the CI environment
• Verify environment variables are properly set

Deployment Issues

• Confirm API keys are valid and have proper permissions
• Check Kantan CMS service status
• Verify repository configuration in CMS settings

Advanced Configuration

Custom Build Environments

You can customize the GitHub Actions environment:

• Use specific Node.js versions
• Install additional dependencies
• Configure custom build tools
• Set up database connections (if needed)

Integration with Other Services

Extend your workflow to integrate with:

• Slack/Discord notifications for deployment status
• Performance monitoring tools
• Content delivery networks (CDNs)
• Analytics and tracking services

Next Steps

Congratulations! You now have a fully automated deployment pipeline that:

• Automatically builds and deploys your website when you push changes
• Integrates your Kantan CMS content seamlessly
• Provides a professional development workflow
• Scales with your team and project needs

Your Kantan CMS setup is now complete with professional-grade automation. You can focus on creating content and developing features while the system handles deployment automatically.