Configuration & Setup

This page is the reference side of Skyhook’s CI/CD. Credential setup — cloud OIDC / Workload Identity, the GitHub Apps, protected branches — lives on GitHub Actions setup. Start there if you’re setting things up for the first time; come back here for the cheat-sheets and the knobs.

Supported cloud stacks

Skyhook’s generated workflows accept a <provider>/<account>/<location>/<cluster> tuple in the cloud_provider_account_location_cluster input and route to the right cloud authentication + registry login automatically. The formats are:

AWS (EKS + ECR)

Cluster tuple: aws/123456789/us-east-1/my-cluster — provider, AWS account ID, region, EKS cluster name. Needs: EKS cluster, ECR repository (created by workflows on first push), and either an IAM role (OIDC, recommended) or static access keys.

GCP (GKE + Artifact Registry)

Cluster tuple: gcp/my-project/us-central1/my-cluster — provider, GCP project ID, location, GKE cluster name. Needs: GKE cluster, Artifact Registry or GCR, and either Workload Identity Federation (recommended) or a service account JSON key.

Azure (AKS + ACR)

Cluster tuple: azure/subscription-id/eastus/my-cluster — provider, subscription ID, region, AKS cluster name. Needs: AKS cluster, ACR, and a service principal or managed identity.

BYOK / other registries

For clusters you operate yourself (on-prem, bare-metal, k3s, DigitalOcean, etc.) and non-cloud registries (Docker Hub, GHCR, Harbor, Quay), cloud CLI setup doesn’t apply. Workflows use a base64-encoded KUBECONFIG secret and standard registry credentials — see GitHub Actions setup → BYOK tab.

Secrets and variables reference

Configure these in GitHub Repository (or Organization) Settings → Secrets and Variables → Actions. Repository variables are for non-sensitive values like role ARNs and service account emails; secrets are for credentials.

Cluster authentication

Provider	Method	Name	Type	Used by
AWS	OIDC (recommended)	`AWS_BUILD_ROLE`	variable	build workflow (ECR)
AWS	OIDC (recommended)	`AWS_DEPLOY_ROLE`	variable	deploy workflow (EKS)
AWS	Access keys	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	secret	build + deploy
GCP	Workload Identity (recommended)	`WIF_PROVIDER`, `WIF_SERVICE_ACCOUNT`	variable	build + deploy
GCP	Service account key	`GCP_CREDENTIALS`	secret	build + deploy
Azure	OIDC federated (recommended)	`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`	variable	build + deploy
Azure	Client secret	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`	secret	build + deploy
BYOK	kubeconfig	`KUBECONFIG`	secret (base64)	deploy

OIDC / WIF and static credentials are alternatives — pick one path per cloud, not both. The AWS_BUILD_ROLE and AWS_DEPLOY_ROLE can point at the same role if you prefer; separating them lets you give each workflow the minimum IAM policy it needs.

Registry credentials

Registry auth is handled automatically for AWS ECR, GCP Artifact Registry, and Azure ACR once cluster authentication is in place. For other registries:

Registry	Name	Type
GitHub Container Registry (GHCR)	uses the built-in `github.token` — no setup needed	—
Docker Hub	`DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`	secret
Private / OCI-compliant	`REGISTRY_USERNAME`, `REGISTRY_PASSWORD`	secret

Cross-repo GitHub access

Required when your service pushes to a separate deployment repository (GitOps) or a central Helm-charts repo:

Method	Names	Type
GitHub App (recommended)	`GH_APP_ID`, `GH_APP_PK`	secret
Personal Access Token	`GHA_PAT`	secret

Skyhook’s Deployment GitHub App flow configures these for you. Use a PAT for quick setups where a single user’s credentials are acceptable.

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@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
- 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. All are open source, versioned, and pinned to @v1 in generated workflows.

Build and tagging

skyhook-io/determine-image-tag@v1 — tag generation with branch, date, and counter components
skyhook-io/docker-build-push-action@v1 — multi-registry Docker build and push with caching
skyhook-io/parse-image-registry@v1 — parse an image URL into provider/registry/repository/tag

Cloud authentication

skyhook-io/cloud-login@v1 — unified AWS/GCP/Azure authentication with optional kubectl and registry login (orchestrator used by the generated workflows)
skyhook-io/login-aws@v1, skyhook-io/login-gcp-gke@v1, skyhook-io/login-azure-aks@v1 — per-cloud building blocks if you want to call them directly
skyhook-io/parse-cloud-provider-cluster@v1 — parse the <provider>/<account>/<location>/<cluster> tuple format
skyhook-io/ensure-ecr-repository@v1 — create an ECR repository if it doesn’t exist

Deployment

skyhook-io/kustomize-deploy@v1 — deploys via kubectl or GitOps depending on how the overlay is configured (orchestrator used by the generated deploy.yml)
skyhook-io/kustomize-edit@v1, skyhook-io/kustomize-inspect@v1, skyhook-io/kustomize-apply@v1 — building blocks for the deploy orchestrator
skyhook-io/parse-deploy-config-source@v1 — parse the [<repo>][@<ref>][:<path>] deploy source string
skyhook-io/patch-env-files@v1 — apply runtime overrides to overlay .env files
skyhook-io/determine-deploy-dir@v1 — find the deployment directory for a service

Waiting for rollouts

skyhook-io/wait-for-deployment@v1 — wait for Kubernetes workloads to become ready; delegates to the Rollout waiter for Argo Rollouts resources (used by the generated deploy.yml when ArgoCD isn’t managing the deploy)
skyhook-io/wait-for-rollout@v1 — wait for a specific Argo Rollout to complete
skyhook-io/wait-for-argocd-sync@v1 — wait for ArgoCD-managed workloads to sync

Matrix generation (monorepos + separate deployment repos)

skyhook-io/generate-service-matrix@v1 — reads .skyhook/skyhook.yaml (or the legacy .koala-monorepo.json) and produces the build/deploy matrix used by release.yml

Cross-repo GitHub access

skyhook-io/github-auth-token@v1 — exchange a PAT or GitHub App credentials for a token scoped to another repository (used when deploying to a separate deployment repo)
skyhook-io/git-sync-commit@v1 — commit and push changes safely with automatic rebase and retry

Jobs

skyhook-io/resolve-job-template@v1, skyhook-io/submit-job@v1 — used by the generated execute_job.yml to discover and trigger Kubernetes CronJobs and Argo Workflows

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
GitHub OIDC Setup - Deep-dive on the recommended cloud-auth path

Introduction

Getting Started

Application Features

Infrastructure & Platform

Observability

Settings

AI Assistant

Terms and Privacy Policy

Configuration & Setup

Supported cloud stacks

AWS (EKS + ECR)

GCP (GKE + Artifact Registry)

Azure (AKS + ACR)

BYOK / other registries

Secrets and variables reference

Cluster authentication

Registry credentials

Cross-repo GitHub access

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

Build and tagging

Cloud authentication

Deployment

Waiting for rollouts

Matrix generation (monorepos + separate deployment repos)

Cross-repo GitHub access

Jobs

Security Best Practices

Next Steps

​Supported cloud stacks

​AWS (EKS + ECR)

​GCP (GKE + Artifact Registry)

​Azure (AKS + ACR)

​BYOK / other registries

​Secrets and variables reference

​Cluster authentication

​Registry credentials

​Cross-repo GitHub access

​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

​Build and tagging

​Cloud authentication

​Deployment

​Waiting for rollouts

​Matrix generation (monorepos + separate deployment repos)

​Cross-repo GitHub access

​Jobs

​Security Best Practices

​Next Steps

Supported cloud stacks

AWS (EKS + ECR)

GCP (GKE + Artifact Registry)

Azure (AKS + ACR)

BYOK / other registries

Secrets and variables reference

Cluster authentication

Registry credentials

Cross-repo GitHub access

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

Build and tagging

Cloud authentication

Deployment

Waiting for rollouts

Matrix generation (monorepos + separate deployment repos)

Cross-repo GitHub access

Jobs

Security Best Practices

Next Steps