@gaodes/pi-gitlab 0.3.0 → 0.4.2

package/skills/gitlab-milestone/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: gitlab-milestone
+description: >
+  GitLab milestone management using the glab CLI and API. Use for
+  listing, creating, and managing project milestones and sprints.
+---
+
+# GitLab Milestone Skill
+
+## Patterns
+
+### List milestones
+```bash
+glab milestone list
+```
+
+### Create a milestone
+```bash
+glab milestone create "v1.0" -d "First stable release"
+```
+
+### List milestones via API (structured)
+```
+gitlab_api({ endpoint: "projects/:project/milestones", project: "namespace/project" })
+```
+
+### Create milestone via API
+```
+gitlab_api({
+  endpoint: "projects/:project/milestones",
+  project: "namespace/project",
+  method: "POST",
+  body: {
+    title: "v1.0",
+    description: "First stable release",
+    due_date: "2026-06-30"
+  },
+  confirm: true
+})
+```
+
+### Update a milestone
+```
+gitlab_api({
+  endpoint: "projects/:project/milestones/:milestone_id",
+  project: "namespace/project",
+  method: "PUT",
+  body: { state_event: "close" },
+  confirm: true
+})
+```
+
+### Delete a milestone
+```
+gitlab_api({
+  endpoint: "projects/:project/milestones/:milestone_id",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- Use milestone IDs (numeric) for update and delete operations.
+- Milestones are project-scoped; group milestones use the group API endpoint.
+- For assigning milestones to issues, use `gitlab-issue` skill.

package/skills/gitlab-protected-branch/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: gitlab-protected-branch
+description: >
+  GitLab protected branch management via API. Use for viewing branch
+  protection rules, protecting and unprotecting branches, and
+  configuring push and merge access levels.
+---
+
+# GitLab Protected Branch Skill
+
+## Patterns
+
+### List protected branches
+```
+gitlab_api({ endpoint: "projects/:project/protected_branches", project: "namespace/project" })
+```
+
+### Get protection details for a branch
+```
+gitlab_api({ endpoint: "projects/:project/protected_branches/:branch_name", project: "namespace/project" })
+```
+
+### Protect a branch
+```
+gitlab_api({
+  endpoint: "projects/:project/protected_branches",
+  project: "namespace/project",
+  method: "POST",
+  body: { name: "main", push_access_level: 40, merge_access_level: 40 },
+  confirm: true
+})
+```
+
+### Update protection (allow force push)
+```
+gitlab_api({
+  endpoint: "projects/:project/protected_branches/:branch_name",
+  project: "namespace/project",
+  method: "PATCH",
+  body: { allow_force_push: true },
+  confirm: true
+})
+```
+
+### Unprotect a branch
+```
+gitlab_api({
+  endpoint: "projects/:project/protected_branches/:branch_name",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- Access levels: 0 = No access, 30 = Developer, 40 = Maintainer, 60 = Admin.
+- Code owner approval requires GitLab Premium.
+- The `gitlab_force_push_safe` tool handles the full protection lifecycle for safe force pushes.
+- Use this skill for general protection management; use `gitlab_force_push_safe` for force-push workflows.

package/skills/gitlab-release/SKILL.md

@@ -2,7 +2,7 @@
 name: gitlab-release
 description: >
   GitLab release management. Use for listing, viewing, and creating
-  releases tied to Git tags on gitlab.elches.dev. Requires glab and
+  releases tied to Git tags on the configured GitLab instance. Requires glab and
   confirm for mutating operations.
 ---
 

package/skills/gitlab-repo/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: gitlab-repo
+description: >
+  GitLab repository and project operations. Use for cloning, forking,
+  viewing project info, creating repositories, and managing project
+  settings.
+---
+
+# GitLab Repository Skill
+
+## Patterns
+
+### View project info (structured tool)
+```
+gitlab_repo_view({ project: "namespace/project" })
+```
+
+### Clone a repository
+```bash
+glab repo clone namespace/project
+```
+
+### Fork a project
+```bash
+glab repo fork namespace/project
+```
+
+### View repo in browser
+```bash
+glab repo view -w
+```
+
+### Create a new project
+```bash
+glab repo create my-project -d "Project description"
+```
+
+### Search repos
+```bash
+glab repo search "search term"
+```
+
+### Archive a project
+```
+gitlab_api({
+  endpoint: "projects/:project/archive",
+  project: "namespace/project",
+  method: "POST",
+  confirm: true
+})
+```
+
+### Delete a project
+```
+gitlab_api({
+  endpoint: "projects/:project",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+### List contributors
+```bash
+glab repo contributors
+```
+
+## Rules
+
+- Use `gitlab_repo_view` for structured project metadata; use `glab repo view` for terminal display.
+- Fork and clone are safe operations; archive and delete require `confirm: true`.
+- Deleting a project is **irreversible** — always confirm explicitly.

package/skills/gitlab-search/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: gitlab-search
+description: >
+  GitLab search across projects, issues, merge requests, code, commits,
+  users, and wiki content. Use for finding resources globally, within a
+  group, or within a project.
+---
+
+# GitLab Search Skill
+
+## Patterns
+
+### Global search (all scopes)
+```
+gitlab_search_query({ query: "search term" })
+```
+
+### Search within a project
+```
+gitlab_search_query({ query: "search term", project: "namespace/project", scope: "blobs" })
+```
+
+### Search within a group
+```
+gitlab_search_query({ query: "search term", group: "group-id", scope: "issues" })
+```
+
+### Search specific scope via API
+```
+gitlab_api({ endpoint: "search", query: { scope: "projects", search: "pi-gitlab" } })
+```
+
+### Project-level code search
+```
+gitlab_api({
+  endpoint: "projects/:project/search",
+  project: "namespace/project",
+  query: { scope: "blobs", search: "function pattern" }
+})
+```
+
+## Rules
+
+- Prefer `gitlab_search_query` for structured search results with automatic pagination.
+- Available scopes: `projects`, `issues`, `merge_requests`, `milestones`, `blobs`, `commits`, `users`, `wiki_blobs`.
+- Search results are limited to resources the authenticated user can access.
+- For listing all items with known filters, prefer dedicated tools (`gitlab_issue_list`, `gitlab_mr_list`) over search.

package/skills/gitlab-variable/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gitlab-variable
+description: >
+  GitLab CI/CD variable management using the glab CLI. Use for listing,
+  creating, updating, and deleting project and group CI/CD variables.
+---
+
+# GitLab CI/CD Variable Skill
+
+## Patterns
+
+### List project variables
+```bash
+glab variable list
+```
+
+### List group variables
+```bash
+glab variable list -g mygroup
+```
+
+### Get a variable value
+```bash
+glab variable get VARIABLE_KEY
+```
+
+### Set a variable
+```bash
+glab variable set DEPLOY_KEY "secret-value" --masked
+```
+
+### Update a variable
+```bash
+glab variable update VARIABLE_KEY "new-value"
+```
+
+### Delete a variable
+```bash
+glab variable delete VARIABLE_KEY
+```
+
+### Export variables
+```bash
+glab variable export
+```
+
+### List variables via API (structured)
+```
+gitlab_api({ endpoint: "projects/:project/variables", project: "namespace/project" })
+```
+
+### Create variable via API
+```
+gitlab_api({
+  endpoint: "projects/:project/variables",
+  project: "namespace/project",
+  method: "POST",
+  body: { key: "DEPLOY_KEY", value: "secret-value", masked: true },
+  confirm: true
+})
+```
+
+## Rules
+
+- Masked variables hide values in job logs.
+- Protected variables only apply to protected branches/tags.
+- Environment-scoped variables use `environment_scope` parameter.
+- All mutating operations require `confirm: true`.
+- Never log or display variable values in plain text.

package/skills/gitlab-vulnerability/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gitlab-vulnerability
+description: >
+  GitLab security vulnerability management via API. Use for listing
+  vulnerabilities, viewing details, confirming, dismissing, or resolving
+  security findings.
+---
+
+# GitLab Vulnerability Skill
+
+## Patterns
+
+### List vulnerabilities
+```
+gitlab_api({ endpoint: "projects/:project/vulnerabilities", project: "namespace/project" })
+```
+
+### Get vulnerability details
+```
+gitlab_api({ endpoint: "projects/:project/vulnerabilities/:vuln_id", project: "namespace/project" })
+```
+
+### Confirm a vulnerability
+```
+gitlab_api({
+  endpoint: "projects/:project/vulnerabilities/:vuln_id/confirm",
+  project: "namespace/project",
+  method: "POST",
+  confirm: true
+})
+```
+
+### Dismiss a vulnerability
+```
+gitlab_api({
+  endpoint: "projects/:project/vulnerabilities/:vuln_id/dismiss",
+  project: "namespace/project",
+  method: "POST",
+  body: { comment: "False positive - not applicable" },
+  confirm: true
+})
+```
+
+### Resolve a vulnerability
+```
+gitlab_api({
+  endpoint: "projects/:project/vulnerabilities/:vuln_id/resolve",
+  project: "namespace/project",
+  method: "POST",
+  confirm: true
+})
+```
+
+### Revert to detected state
+```
+gitlab_api({
+  endpoint: "projects/:project/vulnerabilities/:vuln_id/revert",
+  project: "namespace/project",
+  method: "POST",
+  confirm: true
+})
+```
+
+### List vulnerability findings
+```
+gitlab_api({ endpoint: "projects/:project/vulnerability_findings", project: "namespace/project" })
+```
+
+## Rules
+
+- Full vulnerability management requires GitLab Ultimate tier.
+- Vulnerability states: `detected`, `confirmed`, `dismissed`, `resolved`.
+- All state-change operations require `confirm: true`.
+- For running security scans, use the `gitlab-ci` skill (SAST, DAST jobs).

package/skills/gitlab-webhook/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: gitlab-webhook
+description: >
+  GitLab webhook management via API. Use for listing, creating, updating,
+  and deleting project and group webhooks, and testing webhook delivery.
+---
+
+# GitLab Webhook Skill
+
+## Patterns
+
+### List project webhooks
+```
+gitlab_api({ endpoint: "projects/:project/hooks", project: "namespace/project" })
+```
+
+### Get webhook details
+```
+gitlab_api({ endpoint: "projects/:project/hooks/:hook_id", project: "namespace/project" })
+```
+
+### Create a webhook
+```
+gitlab_api({
+  endpoint: "projects/:project/hooks",
+  project: "namespace/project",
+  method: "POST",
+  body: {
+    url: "https://example.com/hook",
+    push_events: true,
+    merge_requests_events: true
+  },
+  confirm: true
+})
+```
+
+### Update a webhook
+```
+gitlab_api({
+  endpoint: "projects/:project/hooks/:hook_id",
+  project: "namespace/project",
+  method: "PUT",
+  body: { push_events: false, tag_push_events: true },
+  confirm: true
+})
+```
+
+### Delete a webhook
+```
+gitlab_api({
+  endpoint: "projects/:project/hooks/:hook_id",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+### Test webhook delivery
+```
+gitlab_api({
+  endpoint: "projects/:project/hooks/:hook_id/test/push",
+  project: "namespace/project",
+  method: "POST",
+  confirm: true
+})
+```
+
+### List group webhooks
+```
+gitlab_api({ endpoint: "groups/:group_id/hooks" })
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- Webhook URLs must use HTTPS in production.
+- Available event triggers for testing: `push`, `tag_push`, `issues`, `merge_requests`, `wiki_page`.
+- Hook IDs are numeric; list webhooks first to find the ID.
+- Secret tokens are returned only on creation; store them securely.

package/skills/gitlab-wiki/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: gitlab-wiki
+description: >
+  GitLab wiki page management via API. Use for listing, reading, creating,
+  updating, and deleting wiki pages, and uploading attachments.
+---
+
+# GitLab Wiki Skill
+
+## Patterns
+
+### List wiki pages
+```
+gitlab_api({ endpoint: "projects/:project/wikis", project: "namespace/project" })
+```
+
+### Get a wiki page
+```
+gitlab_api({ endpoint: "projects/:project/wikis/:slug", project: "namespace/project" })
+```
+
+### Create a wiki page
+```
+gitlab_api({
+  endpoint: "projects/:project/wikis",
+  project: "namespace/project",
+  method: "POST",
+  body: { title: "Architecture Overview", content: "# Architecture\n\n..." },
+  confirm: true
+})
+```
+
+### Update a wiki page
+```
+gitlab_api({
+  endpoint: "projects/:project/wikis/:slug",
+  project: "namespace/project",
+  method: "PUT",
+  body: { content: "# Updated Architecture\n\n..." },
+  confirm: true
+})
+```
+
+### Delete a wiki page
+```
+gitlab_api({
+  endpoint: "projects/:project/wikis/:slug",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+### Upload a wiki attachment
+```
+gitlab_api({
+  endpoint: "projects/:project/wikis/attachments",
+  project: "namespace/project",
+  method: "POST",
+  body: { file: "path/to/file", branch: "main" },
+  confirm: true
+})
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- Wiki slugs are URL-friendly versions of the title (e.g. "Architecture Overview" → "architecture-overview").
+- Wiki content supports Markdown and RDoc formats.
+- Use `format` field to specify content format: `markdown` (default), `rdoc`, or `asciidoc`.

package/skills/gitlab-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gitlab-workflow
 description: >
-  Cross-domain GitLab workflow orchestration on gitlab.elches.dev.
+  Cross-domain GitLab workflow orchestration on the configured GitLab instance.
   Combines tools into multi-step flows like release cut, hotfix, and
   issue-to-MR pipelines. Routes to focused skills for individual steps.
 ---

package/src/commands/gitlab-doctor.ts

@@ -32,7 +32,10 @@ function versionSatisfies(installed: string, required: string): boolean {
 	return patI >= patR;
 }
 
-export async function runDoctor(pi: ExtensionAPI, cwd?: string): Promise<Check[]> {
+export async function runDoctor(
+	pi: ExtensionAPI,
+	cwd?: string,
+): Promise<Check[]> {
 	const checks: Check[] = [];
 
 	try {
@@ -59,7 +62,8 @@ export async function runDoctor(pi: ExtensionAPI, cwd?: string): Promise<Check[]
 		checks.push({
 			label: "glab CLI",
 			status: "fail",
-			detail: "glab not found in PATH. Install from: https://gitlab.com/gitlab-org/cli#installation",
+			detail:
+				"glab not found in PATH. Install from: https://gitlab.com/gitlab-org/cli#installation",
 		});
 	}
 
@@ -145,7 +149,8 @@ async function runSetupWizard(ctx: ExtensionContext): Promise<boolean> {
 	if (!proceed) return false;
 
 	const hostname =
-		(await ctx.ui.input("GitLab hostname", current.hostname)) ?? current.hostname;
+		(await ctx.ui.input("GitLab hostname", current.hostname)) ??
+		current.hostname;
 	const sshHostname =
 		(await ctx.ui.input("GitLab SSH hostname", current.sshHostname)) ??
 		current.sshHostname;
@@ -183,7 +188,10 @@ async function runSetupWizard(ctx: ExtensionContext): Promise<boolean> {
 		defaultProjectPath,
 	});
 
-	ctx.ui.notify("Saved pi-gitlab configuration to global prime-settings.json", "info");
+	ctx.ui.notify(
+		"Saved pi-gitlab configuration to global prime-settings.json",
+		"info",
+	);
 
 	if (!process.env[tokenEnv] || process.env[tokenEnv]?.trim().length === 0) {
 		ctx.ui.notify(

package/src/config/loader.ts

@@ -98,6 +98,11 @@ export function loadConfig(cwd?: string): PiGitlabConfig {
 		}
 	}
 
+	// Auto-derive apiBase from hostname if not explicitly set
+	if (base.hostname && !base.apiBase) {
+		base.apiBase = `https://${base.hostname}/api/v4`;
+	}
+
 	return base;
 }
 
@@ -145,7 +150,9 @@ export function ensureConfig(): void {
 	});
 }
 
-export function writeConfig(overrides: Partial<PiGitlabConfig>): PiGitlabConfig {
+export function writeConfig(
+	overrides: Partial<PiGitlabConfig>,
+): PiGitlabConfig {
 	const existing = readGlobalSettings();
 	const base = cloneDefaults();
 	if (existing["pi-gitlab"] && typeof existing["pi-gitlab"] === "object") {
@@ -159,6 +166,11 @@ export function writeConfig(overrides: Partial<PiGitlabConfig>): PiGitlabConfig
 		safety: { ...base.safety, ...(overrides.safety ?? {}) },
 	};
 
+	// Auto-derive apiBase from hostname if not explicitly set
+	if (merged.hostname && !merged.apiBase) {
+		merged.apiBase = `https://\${merged.hostname}/api/v4`;
+	}
+
 	writeGlobalSettings({
 		...existing,
 		"pi-gitlab": merged,

package/src/config/types.ts

@@ -23,10 +23,10 @@ export interface PiGitlabConfig {
 }
 
 export const DEFAULT_CONFIG: PiGitlabConfig = {
-	hostname: "gitlab.elches.dev",
-	sshHostname: "gitlab-ssh.elches.dev",
-	sshPort: 2222,
-	apiBase: "https://gitlab.elches.dev/api/v4",
+	hostname: "",
+	sshHostname: "",
+	sshPort: 22,
+	apiBase: "",
 	tokenRef: null,
 	tokenEnv: "PI_GITLAB_TOKEN",
 	defaultProjectId: null,

package/src/index.ts

@@ -24,7 +24,12 @@
  *   gitlab_mr_bulk_approve  — bulk-approve MRs (confirm:true)
  *   gitlab_force_push_safe  — safe force push with branch protection lifecycle (confirm:true)
  *
- * Commands:
+ * Phase 4 search, CI lint, and repo tools:
+ *   gitlab_search_query     — search GitLab across multiple scopes
+ *   gitlab_ci_lint          — validate .gitlab-ci.yml configuration
+ *   gitlab_repo_view        — view project/repository info
+ *
+ * In-package skills (0.3.0):
  *   /gitlab-doctor — diagnostic check for glab, auth, API, and config
  *
  * Configuration lives in prime-settings.json key `pi-gitlab`.
@@ -34,6 +39,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { gitlabDoctorCommand } from "./commands/gitlab-doctor.js";
 import { registerResourcesDiscover } from "./events/resourcesDiscover.js";
 import { registerGitlabApi } from "./tools/gitlab_api.js";
+import { registerGitlabCiLint } from "./tools/gitlab_ci_lint.js";
 import { registerGitlabForcePushSafe } from "./tools/gitlab_force_push_safe.js";
 import { registerGitlabIssueClose } from "./tools/gitlab_issue_close.js";
 import { registerGitlabIssueCreate } from "./tools/gitlab_issue_create.js";
@@ -50,6 +56,8 @@ import { registerGitlabProjectResolve } from "./tools/gitlab_project_resolve.js"
 import { registerGitlabReleaseCreate } from "./tools/gitlab_release_create.js";
 import { registerGitlabReleaseList } from "./tools/gitlab_release_list.js";
 import { registerGitlabReleaseView } from "./tools/gitlab_release_view.js";
+import { registerGitlabRepoView } from "./tools/gitlab_repo_view.js";
+import { registerGitlabSearchQuery } from "./tools/gitlab_search_query.js";
 
 export default function piGitlab(pi: ExtensionAPI) {
 	// Expose in-package skills
@@ -84,4 +92,9 @@ export default function piGitlab(pi: ExtensionAPI) {
 	registerGitlabReleaseCreate(pi);
 	registerGitlabMrBulkApprove(pi);
 	registerGitlabForcePushSafe(pi);
+
+	// Phase 4 search, CI lint, and repo tools
+	registerGitlabSearchQuery(pi);
+	registerGitlabCiLint(pi);
+	registerGitlabRepoView(pi);
 }