Setting up CI/CD Integration

CI/CD Pipeline Connection

Audience: Platform teams ready to connect their hosting, configuration, and deployment services with automated pipelines.

What You’ll Need

Prerequisites Required

This guide shows how to tie together your hosting service, configuration management, packages on the NPM registry, and CDN deployment into a cohesive CI/CD pipeline using GitHub Actions. This assumes you have already set up the individual infrastructure components.

While this guide shows our specific implementation, you can adapt it to your needs using different tools and services. Here’s what you’ll typically need (see Alternative Implementations for other platform options):

Essential Components required before you can start building

• Version Control: To track code changes and enable collaboration (we use GitHub)

• Hosting Service: Where your 1fe application will run (Azure Web App explained here)

• Deployment Target: CDN or cloud storage for hosting widget bundles (CDN Setup explained here)

• Configuration Management: Key-value stores for live configuration settings (Configuration Management explained here)

• Private NPM Registry: Internal registry for publishing and consuming widget packages (NPM Registry Setup explained here)

• CI/CD Automation platform: CI/CD platforms for automation (we use GitHub Actions)

Setup Instructions

Integration Focus

This guide assumes you’ve already completed the setup for each infrastructure component listed above. Our role here is to connect everything together into a cohesive automated pipeline that:

• 🚀 Deploys widget bundles to your CDN automatically
• ⚙️ Updates configuration management with new widget versions
• 🔄 Keeps your hosting service running smoothly with zero downtime
• 🧪 Manages multiple environments with proper approval workflows

Our Suggested Approach

Quick Start with GitHub Actions

We use GitHub Actions, but your team may choose a different CI/CD platform (see Alternative Implementations at the bottom of this page for more options). If you’re using GitHub Actions as your CI/CD platform, we recommend cloning or forking our complete CI/CD repository to get started quickly:

🚀 Clone or Fork: 1fe-ci-cd Repository

What you get: Pre-built workflows, reusable actions, template files, and proven patterns for CI/CD pipelines.

Benefits: Faster setup, automatic updates from the central repository, consistent practices across widget projects, and access to complete examples for reference.

1. Repository Configuration

For a production setup, you need proper repository configuration to enable automated workflows. This involves setting up secrets, environments, and permissions for taking local development work to production.

1.1 Secrets Management

We use GitHub’s secret management system to store sensitive credentials securely. All secrets are stored as repository secrets, never hardcoded in files.

Required Secrets for Our CI/CD Pipeline

You need to configure these secrets in your repository to enable the CI/CD pipeline to deploy your widget:

• CDN Deployment Secret (AKAMAI_NS_SSH_PRIVATE_KEY) - SSH private key for Akamai CDN deployment. This allows the pipeline to upload your built widget files to the content delivery network.

• Configuration Service Secret (AZURE_APP_CONFIG_CONNECTION_STRING) - Azure App Configuration connection string. This enables the pipeline to update configuration metadata when your widget is deployed.

• Package Registry Secrets - Authentication tokens for the internal NPM registry:

• NPM_TOKEN_READONLY_1fe - For reading packages from the registry
• NPM_TOKEN - For publishing your widget package to the internal package registry

Steps to configure secrets

1. Navigate to your repository Settings → Secrets and variables → Actions

2. Click “New repository secret” for each required secret

3. Add the three secrets listed above with values provided by your platform team

4. Ensure repository permissions allow workflows to access secrets

Tip

Getting Secret Values: Contact your platform team or refer to your organization’s internal documentation for the current secret names and values. These are managed centrally and updated regularly.

Resources:

• GitHub Secrets Documentation

• GitHub Variables Documentation

1.2 Environment Configuration

Each widget repository needs environment configuration to control deployment rules and approvals. This ensures proper oversight and prevents unauthorized deployments to production.

Our Environment Setup

We configured two environments for every widget repository:

• Integration Environment - For automated testing and validation of widget changes
• Production Environment - For live user-facing deployments with approval requirements

What it does: Creates separate deployment environments with different approval rules for all environments. Some environments allow automated deployments for testing, while others require manual approval to ensure oversight and control.

Setting up approval groups:

• Create a GitHub team for production approvers (e.g., “Production Approvers”)

• Add the team as required reviewers in the production environment

• Team members will receive notifications when production deployments need approval

• Only team members can approve production releases

Resources:

• GitHub Environments Documentation

• GitHub Teams Documentation

• Required Reviewers Documentation

1.3 Workflow Files in Widget Repositories

Our widget repositories contain the necessary CI/CD workflow files in the .github/workflows/ directory:

Widget Release Workflow

widget-ci.yml - Main CI/CD pipeline for widget releases (calls ci-widgets.yml)

• Triggers on pushes to main branch and pull requests

• Builds, tests, and deploys your widget to the appropriate environment

• Handles the complete release process from code to production

Example: CI/CD Release Workflow Run

Widget Rollback Workflow

rollback-widget.yml - Manual rollback workflow for reverting to previous widget versions (calls reusable-rollback-ci.yml)

• Can be triggered manually when needed

• Allows you to quickly revert to a previous working version

• Useful for emergency situations or when issues are discovered in production

Example: Rollback Workflow Run

Platform Integration

These workflow files are pre-configured to work with the 1fe platform and call into the centralized CI/CD repository (1fe-ci-cd) for the actual pipeline logic.

1.4 Template Workflow Files (1fe-ci-cd Repository)

The centralized 1fe-ci-cd repository contains pre-built workflow files that handle different aspects of the CI/CD pipeline:

File Name	Purpose	Link
ci-widgets.yml	Main orchestrator workflow - coordinates all build, test, and deploy jobs	View source code
reusable-rollback-ci.yml	Handles rollback procedures with asset verification	View source code
reusable-update-azure-config.yml	Updates configuration in external services	View source code
reusable-widget-test-production.yml	Production-specific test suite (lint, unit, contract, E2E)	View source code
reusable-widget-test.yml	Standard test suite for development and integration environments	View source code

1.5 Template Custom Actions (1fe-ci-cd Repository)

The centralized repository includes reusable actions for common CI/CD operations:

Action Name	Purpose	Link
check-cdn-asset	Verifies that assets are properly deployed and accessible	View source code
update-azure-config	Handles configuration updates in external services	View source code
widget-build	Builds the widget, calculates version, and archives artifacts	View source code
widget-test-setup	Sets up the testing environment and dependencies	View source code
widget-upload-akamai	Handles uploading build artifacts to deployment targets	View source code

Note: Our example uses specific cloud services, but you can adapt this to your preferred deployment platform. We link to official documentation rather than implementation details that can go stale quickly.

3. How We Use the Workflows

Our workflow files are present in the widget repository and work as follows:

3.1 Automatic Releases

• widget-ci.yml runs automatically when we:

• Push code to the main branch

• Create or update pull requests

• No manual intervention needed for normal releases. Deployment to integration is automated.

Example Implementation: 1fe Widget Starter Kit CI Run

3.2 Manual Rollbacks

• rollback-widget.yml can be triggered manually when needed:

1. Go to the Actions tab in the GitHub repository

2. Select “Rollback Widget” from the workflow list

3. Click “Run workflow”

4. Enter the target version we want to rollback to

5. Select the target environment

6. Click “Run workflow”

When to Use Rollback

We use the rollback workflow when:

• A production deployment has issues

• We need to quickly revert to a previous working version

• Emergency situations require immediate action

Our Complete Toolchain

Here’s our specific implementation stack with all the tools and services we use:

Our Implementation

Core Platform:

• GitHub Actions - CI/CD automation platform

• GitHub Secrets - Secure credential management

• GitHub Environments - Deployment environment management

Deployment & CDN:

• Akamai CDN - Content delivery and hosting

Configuration Management:

• Azure App Configuration - Version management and feature flags

Development Tools:

• Node.js - Build and test environment

• Yarn - Package management

• TypeScript - Development language

Alternative Implementations

Our example uses GitHub Actions and specific cloud services, but you can implement the same philosophy with different tools:

CI/CD Platforms

• GitHub Actions: GitHub Actions Documentation (recommended)

• GitLab CI/CD: GitLab CI/CD Documentation

• Bitbucket Pipelines: Bitbucket Pipelines Documentation

• Jenkins: Jenkins Documentation

Deployment Platforms

• AWS S3 + CloudFront: AWS S3 Documentation, CloudFront Documentation

• Google Cloud Storage + CDN: Google Cloud Storage Documentation

• Azure Blob Storage + CDN: Azure Storage Documentation

• Vercel / Netlify: Vercel Documentation, Netlify Documentation

Configuration Management

• Azure App Configuration: Azure App Configuration Documentation (recommended)

• AWS Parameter Store: AWS Systems Manager Parameter Store

• HashiCorp Vault: Vault Documentation

• Google Secret Manager: Google Secret Manager Documentation

Next Steps

Complete CI/CD Setup:

• Configure your widget repository with the required secrets and environments
• Ensure your team has proper access and approval permissions
• Test the automated release process in integration environment
• Familiarize yourself with the rollback workflow for emergency situations

Start Building:

1. Configure Widget Development Environment
2. Deploy Your First Widget
3. Explore Platform Utilities