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

# Deployment Repository Options

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:

<CardGroup cols={2}>
  <Card title="In Code Repository" icon="box">
    **All-in-one approach**

    Deployment files live alongside your application code in each service's repository.
  </Card>

  <Card title="Centralized Deployment Repository" icon="boxes-stacked">
    **Separation of concerns**

    All deployment files for all services live in a single, shared deployment repository.
  </Card>
</CardGroup>

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

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

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

<Note>
  Migration currently requires manual steps. Automated switching between
  approaches is planned for a future release. Contact Skyhook support for
  guidance if needed.
</Note>

## GitOps Integration (Optional)

Both approaches work seamlessly with GitOps tools like ArgoCD:

**Option A (Code Repo):**

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

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

| Aspect                          | Code Repo (Option A)          | Centralized Deployment Repo (Option B) |
| ------------------------------- | ----------------------------- | -------------------------------------- |
| **Setup Complexity**            | Simple                        | Moderate                               |
| **Mental Model**                | Easier (one repo per service) | More complex (N+1 repos)               |
| **Access Control**              | Per-service permissions       | Centralized deployment control         |
| **Code + Config Changes**       | Single PR                     | Separate PRs (code vs deployment)      |
| **Rollback**                    | Single revert                 | Coordinate reverts across repos        |
| **Team Structure**              | Unified dev team              | Dev team + Platform team               |
| **Repos to Maintain**           | 1 per service                 | N code repos + 1 deployment repo       |
| **Consistency Across Services** | Each service different        | Enforced by platform team              |
| **Best For**                    | Small teams, fast iteration   | Large orgs, platform engineering       |

## Best Practices

<Tip>
  **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
</Tip>

<Tip>
  **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
</Tip>

<Tip>
  **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)
</Tip>

<Warning>
  **Stay consistent:** Pick one approach for your organization. Mixing
  approaches makes operations confusing and error-prone.
</Warning>