GitLab Integration

/**
 * GitLab integration plugin for releases and repository operations
 * Handles GitLab releases, asset uploads, and repository integration
 */
class GitLab extends Plugin {
  /** Initialize GitLab plugin with authentication and repository validation */
  init(): Promise<void>;
  
  /** Authentication and validation */
  isAuthenticated(): Promise<boolean>;
  isCollaborator(): Promise<boolean>;
  
  /** Get latest version from GitLab releases */
  getLatestVersion(): Promise<string>;
  
  /** Get changelog from GitLab commits and merge requests */
  getChangelog(): Promise<string>;
  
  /** Pre-release hook for milestone validation */
  beforeRelease(): Promise<void>;
  
  /**
   * Create GitLab release
   * @returns Promise resolving to boolean indicating success
   */
  release(): Promise<boolean>;
  
  /** Log release URL after successful release */
  afterRelease(): void;
  
  /** Release management */
  createRelease(): Promise<boolean>;
  checkReleaseMilestones(): Promise<void>;
  getReleaseMilestones(): string[];
  
  /** Asset management */
  uploadAsset(filePath: string): Promise<any>;
  uploadAssets(): Promise<void>;
  
  /** Repository information */
  getWebUrl(): string;
  
  /** API utilities */
  request(endpoint: string, options?: any): Promise<any>;
}

/**
 * Create GitLab release with notes and assets
 * @param options - Release creation options
 * @returns Promise resolving to GitLab release object
 */
createRelease(options: CreateReleaseOptions): Promise<GitLabRelease>;

/**
 * Upload assets to GitLab package registry or generic packages
 * @param assets - Array of asset file paths or glob patterns
 * @returns Promise that resolves when all assets are uploaded
 */
uploadAssets(assets: string[]): Promise<void>;

/**
 * Get GitLab release by tag name
 * @param tag - Git tag name
 * @returns Promise resolving to release object or null if not found
 */
getReleaseByTag(tag: string): Promise<GitLabRelease | null>;

/**
 * Update existing GitLab release
 * @param releaseId - GitLab release ID
 * @param options - Update options
 * @returns Promise resolving to updated release object
 */
updateRelease(releaseId: number, options: UpdateReleaseOptions): Promise<GitLabRelease>;

interface CreateReleaseOptions {
  /** Release tag name */
  tag_name: string;
  /** Release name/title */
  name?: string;
  /** Release description/body */
  description?: string;
  /** Commit SHA or branch for release */
  ref?: string;
  /** Release milestones */
  milestones?: string[];
  /** Released date */
  released_at?: string;
}

interface UpdateReleaseOptions {
  /** Updated release name */
  name?: string;
  /** Updated release description */
  description?: string;
  /** Updated milestones */
  milestones?: string[];
}

interface GitLabRelease {
  /** Release tag name */
  tag_name: string;
  /** Release name */
  name: string;
  /** Release description */
  description: string;
  /** Release date */
  released_at: string;
  /** Release links */
  _links: {
    /** Web URL for the release */
    self: string;
  };
  /** Associated milestones */
  milestones: GitLabMilestone[];
  /** Release assets */
  assets: {
    /** Asset count */
    count: number;
    /** Asset sources */
    sources: GitLabAssetSource[];
    /** Asset links */
    links: GitLabAssetLink[];
  };
}

interface GitLabMilestone {
  /** Milestone ID */
  id: number;
  /** Milestone title */
  title: string;
  /** Milestone description */
  description: string;
  /** Milestone state */
  state: string;
  /** Milestone web URL */
  web_url: string;
}

interface GitLabAssetSource {
  /** Source format (zip, tar.gz, tar.bz2, tar) */
  format: string;
  /** Source download URL */
  url: string;
}

interface GitLabAssetLink {
  /** Asset link ID */
  id: number;
  /** Asset name */
  name: string;
  /** Asset URL */
  url: string;
  /** Asset type */
  link_type: string;
}

/**
 * Get GitLab repository web URL
 * @returns Repository web URL string
 */
getWebUrl(): string;

/**
 * Get GitLab repository API URL
 * @returns Repository API URL string
 */
getApiUrl(): string;

/**
 * Get GitLab project information
 * @returns Promise resolving to project object
 */
getProject(): Promise<GitLabProject>;

interface GitLabProject {
  /** Project ID */
  id: number;
  /** Project name */
  name: string;
  /** Project path */
  path: string;
  /** Project full path */
  path_with_namespace: string;
  /** Project description */
  description: string;
  /** Project web URL */
  web_url: string;
  /** Project HTTP clone URL */
  http_url_to_repo: string;
  /** Project SSH clone URL */
  ssh_url_to_repo: string;
  /** Default branch */
  default_branch: string;
  /** Project visibility */
  visibility: string;
}

interface GitLabOptions {
  /** Enable/disable GitLab plugin entirely */
  disabled?: boolean;
  
  /** Enable/disable GitLab release creation */
  release?: boolean;
  
  /** GitLab personal access token or CI job token for authentication */
  token?: string;
  
  /** Environment variable name for token (default: 'GITLAB_TOKEN') */
  tokenRef?: string;
  
  /** Token header type ('Private-Token' or 'Job-Token') */
  tokenHeader?: string;
  
  /** Release name template (supports context interpolation) */
  releaseName?: string;
  
  /** Release description/notes template (supports context interpolation) */
  releaseNotes?: string;
  
  /** Auto-generate release notes using GitLab's API */
  autoGenerate?: boolean;
  
  /** Asset files to upload (file paths or glob patterns) */
  assets?: string[];
  
  /** GitLab instance origin URL (for self-hosted GitLab) */
  origin?: string;
  
  /** Skip authentication and connectivity checks */
  skipChecks?: boolean;
  
  /** SSL/TLS security settings */
  secure?: boolean;
  
  /** Custom certificate authority file path */
  certificateAuthorityFile?: string;
  
  /** Environment variable for certificate authority file reference */
  certificateAuthorityFileRef?: string;
  
  /** Project milestones to associate with release */
  milestones?: string[];
  
  /** Use project IDs instead of paths in URLs */
  useIdsForUrls?: boolean;
  
  /** Use GitLab generic package repository for assets */
  useGenericPackageRepositoryForAssets?: boolean;
  
  /** HTTP proxy configuration */
  proxy?: string;
  
  /** Request timeout in milliseconds */
  timeout?: number;
  
  /** Number of retry attempts for failed requests */
  retries?: number;
  
  /** Minimum timeout between retries in milliseconds */
  retryMinTimeout?: number;
  
  /** Update existing release if tag already exists */
  update?: boolean;
  
  /** Comments configuration for issue/MR processing */
  comments?: {
    /** Submit comments on resolved issues */
    submit?: boolean;
    /** Include resolved issues in release notes */
    issue?: string;
    /** Include merged MRs in release notes */
    mr?: string;
  };
}

// Basic GitLab release configuration
const result = await runTasks({
  gitlab: {
    release: true,
    releaseName: "Release ${version}",
    assets: ["dist/*.zip", "docs/*.pdf"]
  }
});

// Advanced GitLab configuration with milestones
const result = await runTasks({
  gitlab: {
    release: true,
    releaseName: "🚀 ${name} v${version}",
    releaseNotes: "## Changes\n\n${changelog}\n\n## Installation\n\nnpm install ${name}@${version}",
    milestones: ["v19.0", "Release Candidate"],
    assets: [
      "dist/bundle.min.js",
      "dist/bundle.min.css",
      "docs/api.md"
    ],
    autoGenerate: true,
    update: true
  }
});

// Self-hosted GitLab configuration
const result = await runTasks({
  gitlab: {
    release: true,
    token: process.env.GITLAB_TOKEN,
    origin: "https://gitlab.internal.company.com",
    secure: false,  // For self-signed certificates
    certificateAuthorityFile: "/path/to/ca.crt"
  }
});

// GitLab CI/CD with job token
const result = await runTasks({
  gitlab: {
    release: true,
    tokenRef: "CI_JOB_TOKEN",
    tokenHeader: "Job-Token",
    useGenericPackageRepositoryForAssets: true
  }
});