> ## Documentation index
> The full klickops handbook index is at https://klickops.io/llms.txt
> The HTML of this page is at https://klickops.io/en/docs/git
> Language: en

# Deploying from Git

Connect a repository and let klickops build the image, so a push becomes a deploy.

## What it is

klickops starts at the container image. Connecting a repository adds the step before that: klickops clones your code, builds an image, pushes it to its own registry, and deploys it. A push to the branch you chose becomes a new version running.

It is not a CI system. There are no pipelines, stages, or build matrices, and there is no place to run your tests. If you need those, keep your CI and let it push an image; klickops will happily deploy that instead.

## When you'd use it

- You have a repository and no image, and would rather not maintain a build workflow.
- You want a push to `main` to reach production without a manual step.
- You want a per-pull-request environment to look at before merging.

> [!Not this]
> If your build needs secrets, custom toolchains, or a test suite that must pass first, that belongs in your CI. Build there, push the image, and point klickops at it.

## Connect a repository

1. Go to **Repos** in the organization and connect your provider. GitHub uses an app installation, so klickops never sees a password.
2. Pick the repository and its default branch.
3. klickops inspects the code and proposes how to build it. Accept or override.

From then on the repository is available to every project in the organization, so a second app from the same code needs no second connection.

```diagram-flow
Push to your branch -> klickops builds -> Image in the registry -> New version running
```

## How it builds

| Builder | When it is used | What it needs |
| --- | --- | --- |
| Buildpacks | Default. No Dockerfile in the repository. | Nothing. The language is detected and a production image is produced. |
| Dockerfile | A Dockerfile is present, or you choose it. | Your Dockerfile. klickops builds it as written. |

Builds run in the cluster, isolated, without root. The result is pushed to the registry klickops runs, so your image never leaves the platform unless you configured a registry of your own.

## Watching a build

The project's **Builds** page lists every build with its status and full log. A failed build leaves the running version untouched, which is the useful property: a broken commit does not take production with it.

## Settings reference

| Setting | Default | What it does |
| --- | --- | --- |
| Branch | the repository's default | Which branch a push deploys from. |
| Subpath | repository root | Build from a subdirectory, for a monorepo. |
| Builder | buildpacks | How the image is produced. |
| Previews | off | Builds and deploys an environment per pull request, torn down when it closes. |

## Limits and gotchas

- **A push deploys the branch you picked and nothing else.** Work on other branches builds nothing unless previews are on.
- **The first build is the slow one.** Later builds reuse layers and finish much faster.
- **Build logs are per build.** A build that is gone from the list takes its log with it.
- **Previews cost what they run.** Each open pull request is a running environment, so a repository with twenty of them is twenty environments.

## Related

- [Apps](/docs/apps) is what a build ultimately deploys.
- [Secrets](/docs/secrets) for values the running app needs. Build-time secrets are not supported.