# @kody/gitlab

## Intent

Reusable GitLab REST helpers for Kody agents. One package covers bring-your-own OAuth applications and personal access tokens for projects, issues, merge requests, pipelines, and generic REST. Multi-account routing is an `integrationName` (OAuth) or `secretName` (PAT) parameter — there are no hard-coded personal aliases or project paths.

## What it does

After you connect GitLab to Kody, agents can:

- Call the GitLab REST API with the correct saved credential (`request`, `paginate`)
- Verify which GitLab identity will perform an action (`get-current-user`)
- List and fetch projects, issues, merge requests, and pipelines
- Preview or apply writes (`issues/create`, `issues/update`, `merge-requests/*`, `pipelines/*`)

It does **not** register a GitLab OAuth application for you. There is no built-in GitLab platform app.

Share this listing at https://kody.codes/@kody/gitlab

## Prerequisites / setup

| Lane | Credential | When to use |
| --- | --- | --- |
| **A. Personal access token** | User secret (documented name `gitlabAccessToken`) passed as `secretName` | Fastest for many automations; best for read-only work via `read_api`. |
| **B. Bring-your-own OAuth App** | Saved integration named `gitlab` (or another name you pass as `integrationName`) | When you want refreshable OAuth instead of a PAT. |

Required host for gitlab.com: `gitlab.com`. Self-hosted instances use that instance host instead.

`secretName` selects the PAT lane and ignores `integrationName`.

### Lane A: personal access token

1. Open [GitLab personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens?scopes=api) and create a token. Use `read_api` for read-only helpers, or `api` for writes.
2. Copy the token once. Never paste it into chat.
3. Save it in Kody and approve the host:

```text
https://kody.codes/account/secrets/new?name=gitlabAccessToken&description=GitLab%20personal%20access%20token&allowedHosts=gitlab.com&scope=user
```

4. Call helpers with `secretName: 'gitlabAccessToken'` (or your chosen secret name).

### Lane B: bring-your-own OAuth application

There is no built-in GitLab OAuth app. Create one, then connect it.

1. Open [GitLab applications](https://gitlab.com/-/profile/applications) → **Add new application**.
2. Set the **Redirect URI** exactly to `https://kody.codes/connect/oauth` (self-hosted Kody uses that deployment origin plus `/connect/oauth`).
3. Enable Confidential and the `api` scope (`read_api` plus `read_user` is enough for read-only helpers).
4. Copy the application id and secret. Never paste the secret into chat.
5. Connect:

```text
https://kody.codes/connect/oauth?provider=gitlab&authorizeUrl=https%3A%2F%2Fgitlab.com%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fgitlab.com%2Foauth%2Ftoken&flow=confidential&scopes=api&allowedHosts=gitlab.com&apiBaseUrl=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4&dashboardUrl=https%3A%2F%2Fgitlab.com%2F-%2Fprofile%2Fapplications
```

Decoded: authorize `https://gitlab.com/oauth/authorize`, token `https://gitlab.com/oauth/token`, `flow=confidential`, scopes `api`, host `gitlab.com`. Paste the client ID and secret into the Kody setup form, then authorize GitLab.

Default helper input: omit `integrationName` and `secretName`. The package uses OAuth integration `gitlab`.

Reconnect later at `https://kody.codes/connect/oauth?provider=gitlab` (or `?provider=<your-integration-name>`).

### Self-hosted GitLab

Pass `instanceUrl` (origin) or `apiBaseUrl` (`https://gitlab.example.com/api/v4`) on every call. Approve that instance host on the secret or OAuth connect URL.

OAuth for another instance (change `provider` for extra accounts):

```text
https://kody.codes/connect/oauth?provider=gitlab&authorizeUrl=https%3A%2F%2Fgitlab.example.com%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fgitlab.example.com%2Foauth%2Ftoken&flow=confidential&scopes=api&allowedHosts=gitlab.example.com&apiBaseUrl=https%3A%2F%2Fgitlab.example.com%2Fapi%2Fv4
```

PAT for another instance: use the same `/account/secrets/new` URL with `allowedHosts` set to that host.

### Multiple GitLab identities

Every export accepts optional `integrationName` (OAuth, default `gitlab`) and `secretName` (PAT). Connect extra accounts under their own integration names — for example `gitlab-work` — by changing `provider` in the connect URL. Pass that name on every call. Do not hard-code personal aliases in forks of this package. `account` is accepted as an alias for `integrationName`.

### Mutations

Create, update, merge, retry, cancel, and REST methods other than `GET` / `HEAD` / `OPTIONS` require `dryRun: true` (preview only) or `confirm: true` (live write).

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and dryRun examples.

## Done when

- OAuth integration `gitlab` is connected **or** secret `gitlabAccessToken` is saved with host `gitlab.com` approved
- `get-current-user` returns a `username` for the selected lane
- Mutations refuse without `confirm: true`; `dryRun: true` never writes to GitLab

## Troubleshooting

- `The redirect_uri MUST match the registered callback URL`: callback must be exactly `https://kody.codes/connect/oauth`.
- `401 Unauthorized` with a PAT: expired token, missing scope, or a stray space. Rotate at GitLab token settings and update the secret.
- Self-hosted 401 / host-approval errors: approve the instance host on the secret or OAuth connect URL, and pass `instanceUrl` or `apiBaseUrl`.
- Token exchange fails: GitLab confidential apps require the client secret. Regenerate the secret and reconnect.
- Writes rejected with a mutation-guard error: pass `dryRun: true` or `confirm: true`.

## License

MIT