Skip to main content
When creating services or jobs in Skyhook, you choose how to organize your deployment configuration files (Kubernetes manifests, Kustomize overlays, CI/CD workflows). This decision affects your repository structure and GitOps workflow.

​
Two Approaches

Skyhook supports two deployment repository strategies:

In Code Repository

All-in-one approachDeployment files live alongside your application code in each service’s repository.

Centralized Deployment Repository

Separation of concernsAll deployment files for all services live in a single, shared deployment repository.

​
Option A: Deployment Files in Code Repository

Your service/job repository contains both application code and deployment configuration. Each service has its own repository with everything included.

​
Directory Structure

my-service/
├── src/                           # Application code
│   └── main.go
├── Dockerfile
├── .koala.toml                    # Skyhook configuration
├── deploy/                        # Deployment files
│   ├── base/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── kustomization.yaml
│   └── overlays/
│       ├── dev/
│       │   ├── kustomization.yaml
│       │   └── deployment-patch.yaml
│       └── prod/
│           ├── kustomization.yaml
│           └── deployment-patch.yaml
└── .github/
    └── workflows/
        ├── build_image.yml
        └── deploy.yml

​
When to Use

✅ Best for:
  • Small teams or individual developers
  • Single-service repositories
  • Simpler mental model (everything in one place)
  • Faster iteration (single PR for code + config changes)
  • Services where deployment changes are closely tied to code changes
✅ Advantages:
  • Simplicity - One repository to manage
  • Atomic changes - Code and deployment updated together
  • Single PR review - Reviewers see code + config in same PR
  • Easier rollback - Git revert affects both code and config
⚠️ Considerations:
  • Repository access control is all-or-nothing
  • Deployment config changes require code repo access
  • Multiple services need multiple repos (or monorepo)

​
Configuration in .koala.toml

Example: Deploy files in code repository 
[Repo]
  Name = "my-service"
  GitUser = "myorg"
  URL = "https://github.com/myorg/my-service"
  Path = ""                    # Root of repo (or path if in monorepo)
  IsMonorepo = false
  # No DeploymentRepo = deploy files in same repo

​
How It Works

  1. During creation, Skyhook adds deploy/ directory to your code repository
  2. CI/CD workflows run from the same repository
  3. GitOps tool (like ArgoCD) can watch the deploy/ directory in your code repo (optional)
  4. Changes to either code or config trigger appropriate workflows

​
Option B: Centralized Deployment Repository

All services store their deployment configuration in a single, shared repository separate from application code.

​
Directory Structure

Code repositories (one per service): 
api-gateway/                        # Service 1 code repo
├── src/
│   └── main.go
├── Dockerfile
└── .github/
    └── workflows/
        ├── build_image.yml         # Builds and pushes images
        └── deploy.yml              # Updates central deployment repo

user-service/                       # Service 2 code repo
├── src/
│   └── main.go
├── Dockerfile
└── .github/
    └── workflows/
        ├── build_image.yml
        └── deploy.yml

payment-service/                    # Service 3 code repo
├── src/
│   └── main.go
├── Dockerfile
└── .github/
    └── workflows/
        ├── build_image.yml
        └── deploy.yml
Central deployment repository (deployments - shared by all services): 
deployments/
├── api-gateway/
│   ├── .koala.toml
│   └── deploy/
│       ├── base/
│       │   ├── deployment.yaml
│       │   ├── service.yaml
│       │   └── kustomization.yaml
│       └── overlays/
│           ├── dev/
│           └── prod/
├── user-service/
│   ├── .koala.toml
│   └── deploy/
│       ├── base/
│       └── overlays/
└── payment-service/
    ├── .koala.toml
    └── deploy/
        ├── base/
        └── overlays/

​
When to Use

✅ Best for:
  • Organizations with separate dev and platform teams
  • Platform engineering teams managing multiple services
  • Stricter access control requirements (separate code and deployment permissions)
  • Strong standardization and consistency requirements
  • GitOps-focused workflows with deployment approval processes
✅ Advantages:
  • Single source of truth - All deployment configs in one place
  • Access control - Different teams manage code vs deployment
  • Consistent patterns - Enforce standards across all services
  • Independent evolution - Update deployment configs without touching code repos
  • Centralized governance - Security policies and compliance in one place
  • Clear audit trail - All deployment changes tracked in one repo
⚠️ Considerations:
  • More complex mental model (N+1 repos: one per service + one deployment repo)
  • Coordinating changes across repos
  • Requires CI/CD automation to update deployment repo from code repos
  • Platform team needs to maintain deployment repo structure

​
Configuration in .koala.toml

Example: Centralized deployment repository 
[Repo]
  Name = "my-service"
  GitUser = "myorg"
  URL = "https://github.com/myorg/my-service"
  Path = ""                           # Root of code repo
  IsMonorepo = false
  DeploymentRepo = "myorg/deployment" # Centralized deployment repo
  DeploymentFolderPath = "my-service" # Path within deployment repo
The .koala.toml file lives in the deployment repository at deployment/my-service/.koala.toml.

​
How It Works

  1. During creation, Skyhook uses (or creates) the centralized deployment repository
  2. Workflows in code repos build container images and update the deployment repo
  3. GitOps tool (like ArgoCD) can watch the centralized deployment repository for manifest changes (optional)
  4. Image updates trigger automated commits to the deployment repo from CI/CD

​
Choosing During Creation

When creating a service or job, you’ll see these options under Source Configuration:
  • Keep deployment files in service/job repo - Option A (default, simpler)
  • Use existing deployment repository - Option B (select centralized repo + specify path)
When choosing Option B, you specify:
  1. Repository - The centralized deployment repository (e.g., org/deployments)
  2. Path - Where this service/job lives in that repo (e.g., /api-gateway, /jobs/data-sync)

​
Switching Between Approaches

You can migrate between approaches after creation:

​
From Option A to Option B

  1. Create or identify your centralized deployment repository
  2. Create subdirectory for your service (e.g., deployments/api-gateway/)
  3. Move deploy/ directory and .koala.toml from code repo to deployment repo path
  4. Update workflows in code repo to push manifest updates to centralized deployment repo
  5. Update service/job configuration in Skyhook UI (point to deployment repo + path)
  6. If using GitOps: Update ArgoCD Application to watch deployment repo path

​
From Option B to Option A

  1. Move deploy/ directory and .koala.toml from deployment repo to code repo
  2. Update workflows in code repo to work with local manifests
  3. Update service/job configuration in Skyhook UI (point to code repo)
  4. If using GitOps: Update ArgoCD Application to watch code repo
  5. Optionally remove service directory from centralized deployment repo
Migration currently requires manual steps. Automated switching between approaches is planned for a future release. Contact Skyhook support for guidance if needed.

​
GitOps Integration (Optional)

Both approaches work seamlessly with GitOps tools like ArgoCD: Option A (Code Repo): 
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service-dev
spec:
  source:
    repoURL: https://github.com/org/my-service
    path: deploy/overlays/dev
    targetRevision: main
Option B (Centralized Deployment Repo): 
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service-dev
spec:
  source:
    repoURL: https://github.com/org/deployments # Centralized repo
    path: my-service/deploy/overlays/dev # Service path within
    targetRevision: main

​
Comparison Table

AspectCode Repo (Option A)Centralized Deployment Repo (Option B)
Setup ComplexitySimpleModerate
Mental ModelEasier (one repo per service)More complex (N+1 repos)
Access ControlPer-service permissionsCentralized deployment control
Code + Config ChangesSingle PRSeparate PRs (code vs deployment)
RollbackSingle revertCoordinate reverts across repos
Team StructureUnified dev teamDev team + Platform team
Repos to Maintain1 per serviceN code repos + 1 deployment repo
Consistency Across ServicesEach service differentEnforced by platform team
Best ForSmall teams, fast iterationLarge orgs, platform engineering

​
Best Practices

Start simple: - Use Option A (code repo) when starting out - Migrate to Option B (centralized) once you have 10+ services or need platform control - Don’t prematurely optimize for scale you don’t have yet
When to use centralized deployment repo: - Different teams manage code vs infrastructure/deployment - Need to enforce consistent deployment patterns across services - Platform team wants centralized governance and compliance - Multiple services with similar deployment requirements
Security: - Implement branch protection on deployment repos - Require reviews for production deployment changes - Use CODEOWNERS for deployment repo to ensure platform team review - Separate read vs write permissions (devs read, platform writes)
Stay consistent: Pick one approach for your organization. Mixing approaches makes operations confusing and error-prone.