Configuration & Setup

This guide covers setting up authentication, configuring multi-cloud deployments, and using advanced CI/CD features. Most of this configuration is done once during initial setup.

Multi-Cloud Setup

Skyhook workflows work seamlessly across cloud providers with consistent configuration patterns.

AWS (EKS + ECR)

Requirements:

Amazon EKS cluster
Amazon ECR repository (created automatically by workflows)
IAM role or access keys for GitHub Actions

Cluster format:

aws/123456789/us-east-1/my-cluster

Components:

aws - Cloud provider
123456789 - AWS account ID
us-east-1 - AWS region
my-cluster - EKS cluster name

Authentication options:

✅ Recommended: OIDC with IAM roles (no long-lived credentials)
Alternative: IAM access keys

AWS authentication setup →

GCP (GKE + Artifact Registry)

Requirements:

Google GKE cluster
Google Artifact Registry or GCR
Service account or Workload Identity for GitHub Actions

Cluster format:

gcp/my-project/us-central1/my-cluster

Components:

gcp - Cloud provider
my-project - GCP project ID
us-central1 - GCP location/region
my-cluster - GKE cluster name

Authentication options:

✅ Recommended: Workload Identity Federation (no service account keys)
Alternative: Service account key JSON

GCP authentication setup →

Azure (AKS + ACR)

Requirements:

Azure AKS cluster
Azure Container Registry
Service principal or managed identity for GitHub Actions

Cluster format:

azure/subscription-id/eastus/my-cluster

Components:

azure - Cloud provider
subscription-id - Azure subscription ID
eastus - Azure region
my-cluster - AKS cluster name

Authentication options:

Service principal credentials
Managed identity (for self-hosted runners)

Authentication Setup

AWS Authentication

Option 1: OIDC with IAM Roles (Recommended)

Benefits:

No long-lived credentials to manage
Automatic credential rotation
Better security posture
Follows AWS best practices

Setup steps:

Create OIDC Provider in AWS
- Go to IAM → Identity Providers
- Add provider for token.actions.githubusercontent.com
- Configure audience: sts.amazonaws.com
Create IAM Role
- Create a role with trust policy for GitHub OIDC
- Attach policies: AmazonEKSClusterPolicy, AmazonEC2ContainerRegistryFullAccess
- Note the role ARN
Configure GitHub Repository Variables
- Go to GitHub Repository → Settings → Secrets and Variables → Actions
- Add repository variable: AWS_DEPLOY_ROLE = arn:aws:iam::123456789:role/github-actions-deploy

Option 2: IAM Access Keys

Setup steps:

Create IAM User
- Create user for GitHub Actions
- Attach policies: AmazonEKSClusterPolicy, AmazonEC2ContainerRegistryFullAccess
Generate Access Keys
- Create access key for the user
- Save access key ID and secret access key
Configure GitHub Repository Secrets
- AWS_ACCESS_KEY_ID = your access key ID
- AWS_SECRET_ACCESS_KEY = your secret access key

GCP Authentication

Option 1: Workload Identity Federation (Recommended)

Benefits:

No service account keys to manage
Automatic credential rotation
Better security posture
Follows GCP best practices

Setup steps:

Create Workload Identity Pool and Provider

gcloud iam workload-identity-pools create github-actions \
  --location="global" \
  --display-name="GitHub Actions Pool"

gcloud iam workload-identity-pools providers create-oidc github \
  --workload-identity-pool="github-actions" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository"

Create Service Account and Grant Permissions

gcloud iam service-accounts create github-actions-deploy

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:github-actions-deploy@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/container.developer"

Allow GitHub Repository to Impersonate

gcloud iam service-accounts add-iam-policy-binding \
  github-actions-deploy@PROJECT_ID.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-actions/attribute.repository/ORG/REPO"

Configure GitHub Repository Variables
- WIF_PROVIDER = projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-actions/providers/github
- WIF_SERVICE_ACCOUNT = github-actions-deploy@PROJECT_ID.iam.gserviceaccount.com

Option 2: Service Account Keys

Setup steps:

Create Service Account
- Go to IAM & Admin → Service Accounts
- Create service account with GKE and GCR permissions
Generate Key
- Create JSON key for the service account
- Download the key file
Configure GitHub Repository Secret
- GCP_CREDENTIALS = paste the entire JSON key file contents

GitHub Authentication

For accessing deployment repositories or other GitHub resources:

Option 1: GitHub Apps (Recommended)

Benefits:

Fine-grained permissions
Better security than PATs
Automatic token refresh
Can be installed on multiple repositories

Setup steps:

Create GitHub App with required permissions
Install app on repositories
Configure GitHub secrets:
- GH_APP_ID = your GitHub App ID
- GH_APP_PK = your GitHub App private key

Option 2: Personal Access Tokens

Setup steps:

Create PAT with repo scope
Configure GitHub secret:
- GHA_PAT = your personal access token

Secrets Management

Configure secrets in GitHub Repository Settings → Secrets and Variables → Actions.

Required Secrets by Cloud Provider

AWS with OIDC:

AWS_DEPLOY_ROLE (variable) - IAM role ARN

AWS with Access Keys:

AWS_ACCESS_KEY_ID (secret)
AWS_SECRET_ACCESS_KEY (secret)

GCP with Workload Identity:

WIF_PROVIDER (variable)
WIF_SERVICE_ACCOUNT (variable)

GCP with Service Account Keys:

GCP_CREDENTIALS (secret)

GitHub (if using separate deployment repo):

GH_APP_ID (secret)
GH_APP_PK (secret)
OR GHA_PAT (secret)

Advanced Features

Separate Deployment Repositories

Skyhook supports separating your application code from deployment configuration for better organization and security. Repository structure:

Organization/
├── my-service/          # Application code + Dockerfile
│   ├── src/
│   ├── Dockerfile
│   └── .github/workflows/
└── deployments/         # Kubernetes manifests
    └── services/
        └── my-service/
            ├── base/
            │   ├── deployment.yaml
            │   └── service.yaml
            └── overlays/
                ├── dev/
                ├── staging/
                └── production/

Configuration in .koala.toml:

[repo]
deployment_repo = "Organization/deployments"
deployment_folder_path = "services/my-service"

Benefits:

Separate permissions for code and config
Shared deployment patterns across services
Easier management of multi-service deployments
Security teams can review config changes independently

Deploy Config Source Format

Override the deployment repository or path at runtime using the deploy_config_source input. Format:

[<repo>][@<ref>][:<path>]

Examples:

@feature-branch - Same repo, different branch
:services/payment - Same repo, different path
Acme/deployments@main:services/api - Different repo, specific branch and path
OtherOrg/configs:k8s/staging - Different org, specific path
Empty - Uses repository defaults from .koala.toml

Use cases:

Test configuration from a feature branch
Use different deployment repos for different environments
Override paths for special deployments

Environment Configuration Overrides

Apply runtime configuration changes without modifying files in your repository. Format: JSON object mapping file paths to key-value pairs Example:

{
  "overlays/dev/.env": {
    "DATABASE_URL": "postgres://dev-db:5432/myapp",
    "LOG_LEVEL": "debug",
    "FEATURE_FLAG_NEW_UI": "true"
  },
  "config/settings.yaml": {
    "max_connections": "100",
    "timeout_seconds": "30"
  }
}

Use cases:

Override environment variables per deployment
Test feature flags without code changes
Adjust configuration for specific deployments
Emergency configuration changes

Progressive Delivery with Argo Rollouts

When Argo Rollouts is enabled, Skyhook workflows support advanced deployment strategies. Features:

Canary deployments - Gradually shift traffic to new version
Blue-green deployments - Switch all traffic after validation
Automatic rollback on failures
Traffic splitting and promotion
Success metric monitoring

Workflow behavior:

Deploys new version using rollout strategy
Monitors rollout progress
Waits for manual or automatic promotion
Marks deployment successful only after rollout completes

Rollout strategies: Canary:

strategy:
  canary:
    steps:
    - setWeight: 20
    - pause: {duration: 5m}
    - setWeight: 50
    - pause: {duration: 5m}
    - setWeight: 100

Blue-Green:

strategy:
  blueGreen:
    activeService: my-service
    previewService: my-service-preview
    autoPromotionEnabled: false

Learn more about Argo Rollouts →

Managing Workflows

Generated Workflow Files

When you create a service, Skyhook generates workflows in .github/workflows/:

.github/
└── workflows/
    ├── release.yml          # Automated CI/CD on main
    ├── build_and_deploy.yml # Manual build + deploy
    ├── deploy.yml           # Manual deploy only
    └── build_image.yml      # Manual build only

Updating Workflows

To regenerate workflows after configuration changes:

# Via Skyhook CLI
skyhook update cicd --reset

# For monorepos
skyhook update cicd --reset --monorepo

The --reset flag ensures complete regeneration from templates, incorporating any changes from your .koala.toml configuration. When to regenerate:

Changed cloud provider
Enabled/disabled ArgoCD
Modified deployment repository settings
Updated to latest workflow templates
Added/removed Argo Rollouts

Customizing Workflows

You can customize generated workflows in three ways:

1. Add Custom Steps

Insert additional steps between existing actions:

- name: Build image
  uses: skyhook-io/docker-build-push-action@v1

- name: Security scan
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.IMAGE }}

- name: Run tests
  run: docker run ${{ env.IMAGE }} npm test

- name: Deploy
  uses: skyhook-io/kustomize-deploy-action@v1

2. Override Inputs

Modify default input values:

with:
  environment: ${{ inputs.environment }}
  tag: ${{ inputs.tag }}
  # Add custom input
  slack_webhook: ${{ secrets.SLACK_WEBHOOK }}

3. Replace Actions

Swap Skyhook actions with your own implementations:

# Instead of skyhook-io/cloud-login-action
- name: Custom AWS authentication
  run: |
    aws configure set aws_access_key_id ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws configure set aws_secret_access_key ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws eks update-kubeconfig --name ${{ env.CLUSTER }}

Workflow Actions Reference

Skyhook workflows use composable GitHub Actions published under the skyhook-io organization:

Core Actions

skyhook-io/determine-image-tag-action@v1 - Smart tag generation with branch, date, counter
skyhook-io/docker-build-push-action@v1 - Multi-registry Docker builds with caching
skyhook-io/cloud-login-action@v1 - Universal cloud authentication (AWS/GCP/Azure)
skyhook-io/kustomize-deploy-action@v1 - Smart deployment (GitOps or kubectl)
skyhook-io/parse-cloud-provider-cluster-action@v1 - Parse cloud provider tuple format
skyhook-io/parse-deploy-config-source@v1 - Parse deployment source format
skyhook-io/patch-env-files@v1 - Apply runtime configuration overrides
skyhook-io/rollouts-wait-action@v1 - Wait for Argo Rollouts completion
skyhook-io/github-auth-token-action@v1 - GitHub authentication for cross-repo access

All actions are:

Versioned for stability
Open source and auditable
Maintained by Skyhook
Documented in their respective repositories

Security Best Practices

Use OIDC/Workload Identity - Avoid long-lived credentials whenever possible
Separate Environments - Different clusters for dev/staging/prod with isolated credentials
Protect Main Branch - Require PR reviews before merging to prevent unauthorized deployments
GitOps for Production - Use ArgoCD for critical environments to maintain audit trail
Test in Staging - Always test deployments before production
Monitor Rollouts - Use Argo Rollouts for gradual rollouts with automatic rollback
Tag Production Releases - Use semantic versioning for production deployments
Rotate Credentials - Regularly rotate any long-lived credentials
Audit Access - Review who has access to GitHub secrets and cloud resources
Use Separate Deployment Repos - Isolate configuration from code for better security

Next Steps

Using Workflows - Learn how to deploy your services
Troubleshooting - Resolve common issues
GitOps with ArgoCD - Set up declarative deployments
GitHub Actions Setup - Configure GitHub credentials

Introduction

Getting Started

Application Features

Infrastructure & Platform

Observability

Settings

AI Assistant

Terms and Privacy Policy

​Multi-Cloud Setup

​AWS (EKS + ECR)

​GCP (GKE + Artifact Registry)

​Azure (AKS + ACR)

​Authentication Setup

​AWS Authentication

​Option 1: OIDC with IAM Roles (Recommended)

​Option 2: IAM Access Keys

​GCP Authentication

​Option 1: Workload Identity Federation (Recommended)

​Option 2: Service Account Keys

​GitHub Authentication

​Option 1: GitHub Apps (Recommended)

​Option 2: Personal Access Tokens

​Secrets Management

​Required Secrets by Cloud Provider

​Advanced Features

​Separate Deployment Repositories

​Deploy Config Source Format

​Environment Configuration Overrides

​Progressive Delivery with Argo Rollouts

​Managing Workflows

​Generated Workflow Files

​Updating Workflows

​Customizing Workflows

​1. Add Custom Steps

​2. Override Inputs

​3. Replace Actions

​Workflow Actions Reference

​Core Actions

​Security Best Practices

​Next Steps

Multi-Cloud Setup

AWS (EKS + ECR)

GCP (GKE + Artifact Registry)

Azure (AKS + ACR)

Authentication Setup

AWS Authentication

Option 1: OIDC with IAM Roles (Recommended)

Option 2: IAM Access Keys

GCP Authentication

Option 1: Workload Identity Federation (Recommended)

Option 2: Service Account Keys

GitHub Authentication

Option 1: GitHub Apps (Recommended)

Option 2: Personal Access Tokens

Secrets Management

Required Secrets by Cloud Provider

Advanced Features

Separate Deployment Repositories

Deploy Config Source Format

Environment Configuration Overrides

Progressive Delivery with Argo Rollouts

Managing Workflows

Generated Workflow Files

Updating Workflows

Customizing Workflows

1. Add Custom Steps

2. Override Inputs

3. Replace Actions

Workflow Actions Reference

Core Actions

Security Best Practices

Next Steps