# atmos git

Publish generated configuration and other artifacts to Git as part of your infrastructure workflows.
Atmos manages repository operations with shared authentication, signing settings, and safeguards
that you can reuse locally and in CI.

> ⚠️ Experimental

**Configure Git Repositories**

Define managed repositories, authentication, commit signing, and local Git hooks under the top-level `git` section of `atmos.yaml`.

Configuration Reference[Read more](/cli/configuration/git)

## Managed Repositories

Publish generated files from the CLI, from [`kind: git` lifecycle hooks](/stacks/hooks#kind-git) such as `after.terraform.apply`, or from native CI workflows. Managed repositories support initialization, cloning, pulling, inspection, diffs, commits, pushing, and cleanup by logical name.

Define repositories once under `git.repositories` in `atmos.yaml`, then refer to them everywhere by logical name:

```yaml
git:
  repositories:
    flux-deploy:
      uri: https://github.com/acme/flux-deploy.git
      auth:
        identity: platform-admin

    generated-terraform:
      uri: https://github.com/acme/generated-terraform.git
```

```shell
atmos git clone flux-deploy
atmos git status flux-deploy
atmos git commit flux-deploy --message="Update manifests" --path=clusters/prod
atmos git push flux-deploy
atmos git clean flux-deploy --dry-run
```

Repository names (`flux-deploy`, `generated-terraform`) are arbitrary, user-defined logical keys — not reserved values. Repository configuration follows standard Atmos deep-merge, so repositories can be defined in imported configuration and overridden per environment.

## How It Differs from Plain Git

Every `atmos git` command goes through the shared Atmos Git service, which adds:

- **Authentication via Atmos Auth** — repository `auth.identity` brings linked integrations (such as `github/sts`) along automatically; the ambient credential broker covers the zero-config CI case; your own credential helpers and SSH agent always continue to work.
- **Safety rules** — pulls are always fast-forward-only, force push is never performed, rejected pushes retry with a bounded `pull --rebase` + re-push loop, and path-scoped commits refuse to commit when unrelated dirty files are present.
- **Reconcile semantics** — `atmos git clone` is idempotent: it clones when the workdir is absent and fetches/fast-forwards when it already exists, which makes restored CI caches safe.
- **Automatic workdirs** — managed repositories clone into a deterministic location under the Atmos XDG cache root, so the [native CI cache](/cli/configuration/ci) captures them across runs for free.
- **Native escape hatch** — `init`, `clone`, `pull`, and `push` pass arguments after `--` verbatim to the underlying git invocation (e.g., `atmos git clone flux-deploy -- --no-tags`), so Atmos safety rules and uncommon git flags compose.

## Subcommands

## Related

- [Git Configuration](/cli/configuration/git) — `git.repositories`, `git.hooks`, and `git.list` in `atmos.yaml`
- [`kind: git` hooks](/stacks/hooks#kind-git) — publish artifacts on lifecycle events like `after.terraform.apply`
- [Authentication](/cli/configuration/auth) — identities and integrations used by `auth.identity`
- [CI Configuration](/cli/configuration/ci) — native CI detection used by no-arg `atmos git clone`