@kody/gitlab

Call GitLab projects, issues, merge requests, and pipelines with OAuth or a personal access token.

README.md

101 lines · 5.5 KB · Markdown

@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

Open GitLab personal access tokens and create a token. Use read_api for read-only helpers, or api for writes.
Copy the token once. Never paste it into chat.
Save it in Kody and approve the host:

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

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.

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

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

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