> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyhook.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration & Setup

> Reference for what Skyhook generates into your repo, the secrets and variables it expects, the workflow actions it calls, and how to customize or regenerate.

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](/infrastructure/cicd-setup/github-integration).** 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](/infrastructure/cicd-setup/github-integration).

## 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](/infrastructure/gitops/overview#deployment-github-app) 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`:**

```toml theme={"system"}
[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:**

```json theme={"system"}
{
  "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:**

```yaml theme={"system"}
strategy:
  canary:
    steps:
    - setWeight: 20
    - pause: {duration: 5m}
    - setWeight: 50
    - pause: {duration: 5m}
    - setWeight: 100
```

**Blue-Green:**

```yaml theme={"system"}
strategy:
  blueGreen:
    activeService: my-service
    previewService: my-service-preview
    autoPromotionEnabled: false
```

[Learn more about Argo Rollouts →](https://argoproj.github.io/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:

```bash theme={"system"}
# 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:

```yaml theme={"system"}
- 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:

```yaml theme={"system"}
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:

```yaml theme={"system"}
# 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`](https://github.com/skyhook-io) organization. All are open source, versioned, and pinned to `@v1` in generated workflows.

### Build and tagging

* [`skyhook-io/determine-image-tag@v1`](https://github.com/skyhook-io/determine-image-tag) — tag generation with branch, date, and counter components
* [`skyhook-io/docker-build-push-action@v1`](https://github.com/skyhook-io/docker-build-push-action) — multi-registry Docker build and push with caching
* [`skyhook-io/parse-image-registry@v1`](https://github.com/skyhook-io/parse-image-registry) — parse an image URL into provider/registry/repository/tag

### Cloud authentication

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

### Deployment

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

### Waiting for rollouts

* [`skyhook-io/wait-for-deployment@v1`](https://github.com/skyhook-io/wait-for-deployment) — 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`](https://github.com/skyhook-io/wait-for-rollout) — wait for a specific Argo Rollout to complete
* [`skyhook-io/wait-for-argocd-sync@v1`](https://github.com/skyhook-io/wait-for-argocd-sync) — wait for ArgoCD-managed workloads to sync

### Matrix generation (monorepos + separate deployment repos)

* [`skyhook-io/generate-service-matrix@v1`](https://github.com/skyhook-io/generate-service-matrix) — 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`](https://github.com/skyhook-io/github-auth-token) — 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`](https://github.com/skyhook-io/git-sync-commit) — commit and push changes safely with automatic rebase and retry

### Jobs

* [`skyhook-io/resolve-job-template@v1`](https://github.com/skyhook-io/resolve-job-template), [`skyhook-io/submit-job@v1`](https://github.com/skyhook-io/submit-job) — used by the generated `execute_job.yml` to discover and trigger Kubernetes CronJobs and Argo Workflows

## 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

* [Using Workflows](/application/cicd/workflows) - Learn how to deploy your services
* [Troubleshooting](/application/cicd/troubleshooting) - Resolve common issues
* [GitOps with ArgoCD](/infrastructure/gitops/overview) - Set up declarative deployments
* [GitHub Actions Setup](/infrastructure/cicd-setup/github-integration) - Configure GitHub credentials
* [GitHub OIDC Setup](/infrastructure/cicd-setup/github-oidc) - Deep-dive on the recommended cloud-auth path