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

# lua git

> Opt-in git auto-commits for push, version, and pull operations, with optional GitHub auto-push

`lua git` turns on automatic git commits for the Lua operations that change your project or its versions, and links a GitHub account so those commits can be pushed to `origin`. It only writes to your local repository and `lua.skill.yaml`; nothing changes on the Lua platform or for end users.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua git connect [--auto-push]
lua git disconnect
lua git status
lua git auth github [--force]
lua git auth status
lua git auth disconnect [provider]
```

## Description

`connect` checks, in order, that `git` is on `PATH`, that the project is inside a repository, and that `user.email` and `user.name` are configured. On the first failure it prints the exact `git` command that fixes it and writes nothing; it never runs `git init` or `git config` for you. When every check passes it writes `git: { enabled: true }` to `lua.skill.yaml`. With `--auto-push` it also requires a linked GitHub account and an `origin` remote of the form `https://github.com/<owner>/<repo>.git`, then writes `git.autoPush: true` as well.

Once enabled, these operations commit automatically: bare [`lua push`](/reference/cli/push) and `lua push all` (a single-primitive push or `lua push backup` does not commit), [`lua version create`](/reference/cli/version) (a commit tagged `lua/v<n>`, with the commit hash recorded on the agent version), `lua version promote` and `lua version delete` (audit commits with no file changes), and [`lua pull`](/reference/cli/pull). Commit messages start with `lua: `, for example `lua: push staged code` and `lua: promote v3 to production`. With auto-push on, each commit is pushed to `origin` using the linked account. A git or push failure never fails the Lua operation.

`disconnect` sets `git.enabled: false` and leaves existing commits and tags untouched. `status` prints whether the integration is enabled, the git version, the configured identity, and the most recent `lua:` commit and `lua/` tag; it does not contact the server.

`auth github` links a GitHub account through the OAuth device flow and stores the token under `~/.lua-cli/`. If an account is already linked it asks `Already linked to GitHub as @<user>. Re-link?` unless `--force`. `auth status` shows the linked user, the granted scopes, and when it was linked. `auth disconnect [provider]` removes the stored token; `github` is the default and the only supported provider.

## Arguments

| Argument     | Values   | Description                                                                                         |
| ------------ | -------- | --------------------------------------------------------------------------------------------------- |
| `[provider]` | `github` | `auth disconnect` only. Any other value prints `Unknown provider: <name>. v1 only supports github.` |

## Options

| Option        | Description                                                                                                 | Default |
| ------------- | ----------------------------------------------------------------------------------------------------------- | ------- |
| `--auto-push` | `connect`: also push every auto-commit to the GitHub `origin` remote. Requires `lua git auth github` first. | off     |
| `--force`     | `auth github`: re-link without the confirmation prompt.                                                     | off     |
| `--device`    | `auth github`: deprecated and ignored; the device flow is always used.                                      | —       |

## Examples

Enable auto-commits for this project; the command never prompts, so the CI form only adds `--ci`:

```bash theme={null}
lua git connect --ci
```

Link GitHub, then enable auto-commits that also push:

```bash theme={null}
lua git auth github
lua git connect --auto-push
```

Inspect the integration. Before `connect`, `status` prints one line:

```bash theme={null}
lua git status
```

```text Output theme={null}
Git integration: disabled (run `lua git connect` to enable)
```

Check whether a GitHub account is linked:

```bash theme={null}
lua git auth status
```

```text Output theme={null}
Not linked. Run `lua git auth github` to link.
```

Stop auto-commits and remove the stored GitHub token:

```bash theme={null}
lua git disconnect
lua git auth disconnect github
```

## Exit codes

| Code | Meaning                                                                                                                                                                                     |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Success, including a declined re-link prompt, `Not linked to github. Nothing to do.`, and `Unknown provider: <name>. v1 only supports github.`                                              |
| `1`  | A `connect` precondition failed (no git binary, not a repository, no identity, no linked GitHub account, no GitHub HTTPS `origin`), or the device flow failed. The hint line names the fix. |
| `2`  | `connect` or `disconnect` run outside a project (`No lua.skill.yaml found. Please run this command from a skill directory.`).                                                               |

## See also

* [Release an agent](/ship/releasing) — what `lua version create` tags
* [`lua version`](/reference/cli/version)
* [`lua pull`](/reference/cli/pull)
* [`lua.skill.yaml`](/reference/cli/lua-skill-yaml) — the `git` section