# @kody/gitlab — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Auth is the
saved OAuth integration **`gitlab`** / **`gitlab-*`** or user secret
**`gitlabAccessToken`** (or your chosen `secretName`) — never paste tokens.
Do not disable live webhooks or jobs.

## Auth

| Lane | Credential | Notes |
| --- | --- | --- |
| OAuth (BYO app) | Integration `gitlab` or `gitlab-<purpose>` | Reconnect `https://kody.codes/connect/oauth?provider=gitlab` |
| PAT | User secret `gitlabAccessToken` (or custom name via `secretName`) | Fast single-identity lane; `read_api` or `api` |

| Call | Resolves to |
| --- | --- |
| omit both | OAuth integration `gitlab` |
| `integrationName: 'gitlab-work'` | that exact OAuth name |
| `secretName: 'gitlabAccessToken'` | PAT lane (ignores `integrationName`) |
| `account: 'work'` | alias for `integrationName: 'work'` / `gitlab-work` style names |

Required host (gitlab.com): `gitlab.com`. Self-hosted: pass `instanceUrl` or
`apiBaseUrl` and approve that host. REST base default:
`https://gitlab.com/api/v4`.

## Import paths

| Export | Import |
| --- | --- |
| overview | `kody:@kody/gitlab` |
| accounts | `kody:@kody/gitlab/accounts` |
| get-current-user | `kody:@kody/gitlab/get-current-user` |
| paginate | `kody:@kody/gitlab/paginate` |
| request | `kody:@kody/gitlab/request` |
| types | `kody:@kody/gitlab/types` |
| projects/list | `kody:@kody/gitlab/projects/list` |
| projects/get | `kody:@kody/gitlab/projects/get` |
| issues/list | `kody:@kody/gitlab/issues/list` |
| issues/get | `kody:@kody/gitlab/issues/get` |
| issues/create | `kody:@kody/gitlab/issues/create` |
| issues/update | `kody:@kody/gitlab/issues/update` |
| merge-requests/list | `kody:@kody/gitlab/merge-requests/list` |
| merge-requests/get | `kody:@kody/gitlab/merge-requests/get` |
| merge-requests/create | `kody:@kody/gitlab/merge-requests/create` |
| merge-requests/update | `kody:@kody/gitlab/merge-requests/update` |
| merge-requests/merge | `kody:@kody/gitlab/merge-requests/merge` |
| pipelines/list | `kody:@kody/gitlab/pipelines/list` |
| pipelines/get | `kody:@kody/gitlab/pipelines/get` |
| pipelines/create | `kody:@kody/gitlab/pipelines/create` |
| pipelines/retry | `kody:@kody/gitlab/pipelines/retry` |
| pipelines/cancel | `kody:@kody/gitlab/pipelines/cancel` |

Prefer static `kody:@kody/gitlab/...` imports from `execute`. Do not lead with
`packages.invoke`.

Project locators: `{ project }`, `{ projectId }`, `{ projectPath }`, or
`{ projectUrl }`. Issue / merge-request / pipeline locators also accept the
matching `*Url` or `iid` aliases.

## Smoke test (read-only)

Package overview (no credentials):

```ts
import describeGitlab from 'kody:@kody/gitlab'

export default async function main() {
	return await describeGitlab()
}
```

Identity (OAuth):

```ts
import getGitlabCurrentUser from 'kody:@kody/gitlab/get-current-user'

export default async function main() {
	return await getGitlabCurrentUser()
}
```

Identity (PAT):

```ts
import getGitlabCurrentUser from 'kody:@kody/gitlab/get-current-user'

export default async function main() {
	return await getGitlabCurrentUser({ secretName: 'gitlabAccessToken' })
}
```

Extra OAuth identity:

```ts
import getGitlabCurrentUser from 'kody:@kody/gitlab/get-current-user'

export default async function main() {
	return await getGitlabCurrentUser({ integrationName: 'gitlab-work' })
}
```

REST read (default OAuth `gitlab`):

```ts
import gitlabRequest from 'kody:@kody/gitlab/request'

export default async function main() {
	const response = await gitlabRequest({
		path: '/projects',
		query: { membership: true, per_page: 5 },
		throwOnError: true,
	})
	return response.data
}
```

## dryRun / confirm (writes)

Create, update, merge, retry, cancel, and REST methods other than
`GET` / `HEAD` / `OPTIONS` require `confirm: true`. Pass `dryRun: true` to
preview without writing to GitLab.

```ts
import createGitlabIssue from 'kody:@kody/gitlab/issues/create'

export default async function main() {
	return await createGitlabIssue({
		project: 'example-group/example-project',
		title: 'Example',
		dryRun: true,
	})
}
```

```ts
import gitlabRequest from 'kody:@kody/gitlab/request'

export default async function main() {
	return await gitlabRequest({
		method: 'POST',
		path: '/projects/example-group%2Fexample-project/issues',
		body: { title: 'Example', description: 'Preview only' },
		dryRun: true,
	})
}
```

## Edge cases

- `secretName` forces the PAT lane and ignores `integrationName`.
- There is no built-in GitLab platform OAuth app — callers must BYO.
- Do not hard-code personal aliases or project paths in forks.
- Prefer package helpers over raw `createAuthenticatedFetch('gitlab')` or
  `{{secret:gitlabAccessToken}}` unless debugging auth bootstrap.