@kody/gitlab

@kody/gitlab — agent notes

Human setup and intent live in 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

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

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):

import describeGitlab from 'kody:@kody/gitlab'

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

Identity (OAuth):

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

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

Identity (PAT):

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

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

Extra OAuth identity:

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):

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.

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,
	})
}

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.