Skip to main content
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

ProviderMethodNameTypeUsed by
AWSOIDC (recommended)AWS_BUILD_ROLEvariablebuild workflow (ECR)
AWSOIDC (recommended)AWS_DEPLOY_ROLEvariabledeploy workflow (EKS)
AWSAccess keysAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYsecretbuild + deploy
GCPWorkload Identity (recommended)WIF_PROVIDER, WIF_SERVICE_ACCOUNTvariablebuild + deploy
GCPService account keyGCP_CREDENTIALSsecretbuild + deploy
AzureOIDC federated (recommended)AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_IDvariablebuild + deploy
AzureClient secretAZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_IDsecretbuild + deploy
BYOKkubeconfigKUBECONFIGsecret (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:
RegistryNameType
GitHub Container Registry (GHCR)uses the built-in github.token — no setup needed—
Docker HubDOCKERHUB_USERNAME, DOCKERHUB_TOKENsecret
Private / OCI-compliantREGISTRY_USERNAME, REGISTRY_PASSWORDsecret

​
Cross-repo GitHub access

Required when your service pushes to a separate deployment repository (GitOps) or a central Helm-charts repo:
MethodNamesType
GitHub App (recommended)GH_APP_ID, GH_APP_PKsecret
Personal Access TokenGHA_PATsecret
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

​
Cloud authentication

​
Deployment

​
Waiting for rollouts

​
Matrix generation (monorepos + separate deployment repos)

​
Cross-repo GitHub access

​
Jobs

​
Security Best Practices

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

​
Next Steps