essesseff Onboarding Utility

Automate essesseff app creation and Argo CD setup using the essesseff Public API with a simple command-line utility.

The essesseff onboarding utility is a command-line tool that automates the process of creating new essesseff apps and configuring Argo CD deployments using the essesseff Public API.

Overview

The essesseff onboarding utility streamlines the app creation and Argo CD setup process by:

Automating app creation: Creates essesseff apps with all 9 repositories via the API
Configuring Argo CD: Sets up Argo CD applications for multiple environments in one command
Handling complexity: Manages rate limiting, error handling, and validation automatically
Providing visibility: Offers verbose logging and clear error messages

Repository

The essesseff onboarding utility is available as an open-source tool:

GitHub Repository: essesseff/essesseff-onboarding-utility

Features

List Templates: View all available templates (global and account-specific)
Create Apps: Automatically create essesseff apps with all 9 repositories
Setup Argo CD: Configure Argo CD applications for dev, qa, staging, and/or prod environments
Rate Limiting: Automatically respects essesseff API rate limits (3 requests per 10 seconds)
Error Handling: Comprehensive error handling with clear messages
Verbose Logging: Optional verbose mode for debugging

Prerequisites

Before using the essesseff onboarding utility, ensure the following prerequisites are met:

Required Prerequisites

GitHub Organization Setup:
- GitHub organization must already exist
- essesseff GitHub App must already be installed in the GitHub organization
- Organization must be linked to the essesseff account (via essesseff UI)
System Dependencies:
- bash (version 4.0 or higher)
- curl (for API calls)
- git (for repository cloning)
- jq (for JSON parsing)
- kubectl (required if using --setup-argocd)
kubectl Configuration (required for --setup-argocd):
- kubectl must be installed and configured for each target environment
- Kubernetes cluster access must be available for each target environment
- Proper permissions to create secrets, configmaps, and Argo CD applications
- Important: kubectl configuration is a prerequisite that must be completed before running the utility
essesseff API Key:
- Valid essesseff API key with appropriate permissions
- API key must belong to the account specified in ESSESSEFF_ACCOUNT_SLUG
- See: essesseff Public API for API key creation and management
GitHub Machine User (required for --setup-argocd):
- GitHub machine user account created
- Personal Access Token (PAT) with repo and read:packages scopes
- Machine user added to the GitHub organization
- See: GitHub Argo CD Machine User Setup Guide

Installation

Clone the repository:

git clone https://github.com/essesseff/essesseff-onboarding-utility.git
cd essesseff-onboarding-utility

Make the script executable:
```
chmod +x essesseff-onboard.sh
```
Copy the example configuration file:
```
cp .essesseff.example .essesseff
```
Edit .essesseff and fill in your configuration values

Configuration

The utility reads configuration from a .essesseff file (by default). Create this file by copying .essesseff.example and filling in your values.

Required Configuration Variables

For all operations:

ESSESSEFF_API_KEY - Your essesseff API key
ESSESSEFF_ACCOUNT_SLUG - Your essesseff team account slug
GITHUB_ORG - GitHub organization login
APP_NAME - essesseff app name (must conform to GitHub repository naming standards)

For --create-app:

TEMPLATE_NAME - Name of the template to use (e.g., "essesseff-hello-world-go-template")
TEMPLATE_IS_GLOBAL - Set to true for global templates, false for account-specific templates

For --setup-argocd:

ARGOCD_MACHINE_USER - Argo CD machine user username
GITHUB_TOKEN - GitHub Personal Access Token for the machine user
ARGOCD_MACHINE_EMAIL - Email address for the machine user

Optional Configuration Variables

ESSESSEFF_API_BASE_URL - essesseff API base URL (defaults to https://essesseff.com/api/v1)
APP_DESCRIPTION - App description (optional for --create-app)
REPOSITORY_VISIBILITY - Repository visibility: private or public (default: private)

App Name Requirements

App names must conform to GitHub repository naming standards:

Allowed characters: lowercase letters (a-z), numbers (0-9), and dashes (-)
Cannot start or end with a dash
Examples: my-app, hello-world, app123 ✅
Invalid: My-App, my_app, -my-app, my-app- ❌

Usage

List Available Templates

List all available templates (global and account-specific):

./essesseff-onboard.sh --list-templates --config-file .essesseff

Filter templates by programming language:

./essesseff-onboard.sh --list-templates --language go --config-file .essesseff

Create essesseff App

Create a new essesseff app (without Argo CD setup):

./essesseff-onboard.sh --create-app --config-file .essesseff

Create App and Setup Argo CD

Create a new essesseff app and set up Argo CD for all environments:

./essesseff-onboard.sh \
  --create-app \
  --setup-argocd dev,qa,staging,prod \
  --config-file .essesseff

Setup Argo CD Only

Set up Argo CD for specific environments (app already exists):

./essesseff-onboard.sh \
  --setup-argocd dev,qa \
  --config-file .essesseff

Verbose Output

Enable verbose output for debugging:

./essesseff-onboard.sh --create-app --verbose --config-file .essesseff

Command-Line Options

--list-templates - List all available templates (global and account-specific)
--language LANGUAGE - Filter templates by language (go, python, node, java)
--create-app - Create a new essesseff app
--setup-argocd ENVS - Comma-separated list of environments (dev,qa,staging,prod)
--config-file FILE - Path to configuration file (default: .essesseff)
--verbose - Enable verbose output
-h, --help - Show help message

How It Works

App Creation Process

Validates app name conforms to GitHub repository naming standards
Checks if app already exists in the specified organization
Fetches template details (global or account-specific based on configuration)
Creates the essesseff app via API (creates all 9 repositories)
Polls for app creation completion

Argo CD Setup Process

Downloads notifications-secret.yaml once (contains secrets for all environments)
For each specified environment:
- Clones the Argo CD environment repository ({app-name}-argocd-{env})
- Creates .env file with only necessary variables
- Copies notifications-secret.yaml to the repository
- Executes setup-argocd.sh script

Note: The utility assumes kubectl is properly configured for each target environment. This is a prerequisite that must be completed before running the utility.

Environment Variables in .env Files

When setting up Argo CD, the utility creates .env files in each Argo CD repository with only the variables required by setup-argocd.sh:

ARGOCD_MACHINE_USER
GITHUB_TOKEN
ARGOCD_MACHINE_EMAIL
GITHUB_ORG
APP_NAME
ENVIRONMENT (set per-environment: dev, qa, staging, or prod)

API-related variables (ESSESSEFF_API_KEY, ESSESSEFF_API_BASE_URL, ESSESSEFF_ACCOUNT_SLUG) and app creation variables (APP_DESCRIPTION, REPOSITORY_VISIBILITY, TEMPLATE_NAME, TEMPLATE_IS_GLOBAL) are NOT copied to the .env files as they are not needed by setup-argocd.sh.

Rate Limiting

The utility automatically respects the essesseff API rate limit of 3 requests per 10 seconds by waiting 4 seconds before each API call. This ensures compliance with the rate limit.

If a rate limit error (HTTP 429) is encountered, the utility will automatically retry after a 10-second wait.

Error Handling

Validates all configuration before making API calls
Checks prerequisites (kubectl, git, etc.)
Provides clear error messages with guidance
Continues with other environments if one fails (for --setup-argocd)
Handles HTTP 429 (rate limit) errors with automatic retry

Validation

After running the onboarding utility, validate the setup:

essesseff.com UI: Verify all 9 repositories exist, check repository visibility, confirm webhook configuration
Argo CD UI: Verify Argo CD applications are created, check application sync status, validate repository connections, confirm notification webhooks are configured

Troubleshooting

kubectl Not Configured

Error: kubectl is not properly configured or cannot connect to cluster

Solution: Configure kubectl for the target environment before running the utility. This is a prerequisite.

App Already Exists

Error: App 'my-app' already exists in organization 'my-org'

Solution: Choose a different app name or delete the existing app first.

Repository Clone Fails

Error: Failed to clone repository: my-app-argocd-dev

Solution:

Ensure the app was created successfully
Verify you have access to the repository
Check that the repository exists in the GitHub organization

API Rate Limit

Warning: Rate limit exceeded, waiting 10 seconds before retry...

Solution: The utility automatically handles rate limits. If you see this message, the utility will retry automatically.

Authentication Errors

Error: HTTP 401 - Missing or invalid Authorization header