# jenkins-actions

**Repository Path**: seanly/jenkins-actions

## Basic Information

- **Project Name**: jenkins-actions
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-14
- **Last Updated**: 2025-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jenkins Actions Shared Library

这是一个 Jenkins Shared Library，用于从 Git 仓库下载 actions 目录并重命名为 `.actions`。

## 功能特性

- 支持 `github.com/owner/repo@branch` 格式的仓库地址
- 自动解析仓库地址和分支名
- 稀疏检出，只下载 actions 目录
- 自动清理临时文件
- 支持默认分支（main）
- 自动检测和隐藏敏感参数

## 插件依赖

### 必需插件

以下插件需要在 Jenkins 中安装才能正常使用此库：

| 插件名称 | 版本要求 | 用途 |
|---------|---------|------|
| [Pipeline: Groovy](https://plugins.jenkins.io/workflow-cps/) | 2.61+ | 支持 Groovy Pipeline 脚本 |
| [Git](https://plugins.jenkins.io/git/) | 4.0+ | Git 仓库操作 |
| [File Operations](https://plugins.jenkins.io/file-operations/) | 1.12+ | 文件复制、删除操作 |
| [Mask Passwords](https://plugins.jenkins.io/mask-passwords/) | 3.0+ | 敏感信息隐藏 |
| [Pipeline Utility Steps](https://plugins.jenkins.io/pipeline-utility-steps/) | 2.0+ | 文件存在性检查 |

### 安装方法

1. 进入 Jenkins 管理页面
2. 选择 "Manage Jenkins" > "Manage Plugins"
3. 在 "Available" 标签页中搜索并安装上述插件
4. 重启 Jenkins 服务

### 版本兼容性

- **Jenkins 版本**: 2.138+
- **Pipeline 插件**: 2.61+
- **Java 版本**: 8+

## 安装配置

### 1. 在 Jenkins 中配置 Shared Library

1. 进入 Jenkins 管理页面
2. 选择 "Manage Jenkins" > "Configure System"
3. 找到 "Global Pipeline Libraries" 部分
4. 添加新的库配置：
   - **Name**: `jenkins-actions`
   - **Default version**: `main` (或你想要的默认分支)
   - **Source Code Management**: Git
   - **Project Repository**: 你的库仓库地址
   - **Credentials**: 如果需要的话

### 2. 在 Pipeline 中使用

```groovy
@Library('jenkins-actions') _

pipeline {
    agent any
    environment {
        ACTIONS_PATH = '.jenkins/actions'  // 默认 actions 路径
    }
    
    stages {
        stage('Checkout Actions') {
            steps {
                script {
                    // 安装 actions，自动设置 env.ACTIONS_PATH
                    installActions('github.com/seanly/jenkins-actions@main')
                    
                    // 使用默认路径（如果未安装）
                    // runAction('hello', ["name=world"])
                }
            }
        }
    }
}
```

## 使用示例

### 基本用法
```groovy
installActions('github.com/seanly/jenkins-actions@main')
```

### 使用默认分支
```groovy
installActions('github.com/seanly/jenkins-actions')
```

### 使用完整 URL
```groovy
installActions('https://github.com/seanly/jenkins-actions@develop')
```

### 执行 Action 脚本
```groovy
// 安装 actions，自动设置 env.ACTIONS_PATH
installActions('github.com/seanly/jenkins-actions@main')

// 基本参数
runAction('hello', ["name=world", "world=hello"], env.ACTIONS_PATH)

// 包含敏感参数（自动隐藏）
runAction('hello', [
    "name=admin", 
    "password=secret123", 
    "api_token=abc123def456"
], env.ACTIONS_PATH)

// 使用默认路径（如果 actions 已存在于 .jenkins/actions）
runAction('hello', ["name=world"])
```

## 环境变量和配置文件

### 自动设置的环境变量
- `ACTIONS_PATH`: actions 安装路径，默认为 `.jenkins/actions`

### 生成的配置文件
- `.jenkins/.env`: 包含 actions 路径的配置文件
  ```
  ACTIONS_PATH=.jenkins/actions
  ```

## 敏感参数处理

该库自动检测并隐藏敏感参数，支持以下关键词：
- `password` - 密码
- `token` - 令牌
- `secret` - 密钥
- `key` - 密钥
- `credential` - 凭据
- `auth` - 认证

包含这些关键词的参数值在 Jenkins 日志中会被自动隐藏，显示为 `****`。

## 目录结构

```
jenkins-actions/
├── vars/
│   └── checkoutActions.groovy    # 全局函数
├── src/
│   └── org/example/
│       └── Pipeline.groovy       # 高级 API 类
├── Jenkinsfile                   # 示例 Pipeline
└── README.md                     # 说明文档
```

## 注意事项

- 确保目标仓库包含 `actions` 目录
- 函数会自动清理临时克隆的目录
- 下载的 actions 目录会被重命名为 `.actions`
- 支持 HTTPS 和 SSH 协议（需要配置相应的凭据）

## 故障排除

如果遇到问题，请检查：

### 插件依赖检查
1. 确保所有必需插件已正确安装
2. 检查插件版本是否满足要求
3. 确认 Jenkins 版本兼容性

### 功能问题检查
1. Jenkins Shared Library 配置是否正确
2. 目标仓库是否存在且可访问
3. 仓库中是否包含 `actions` 目录
4. 网络连接是否正常

### 常见错误及解决方案

| 错误信息 | 可能原因 | 解决方案 |
|---------|---------|---------|
| `Unknown parameter(s) found for class type` | File Operations 插件版本过低 | 升级到 1.12+ 版本 |
| `fileExists is not a member of class` | Pipeline Utility Steps 插件未安装 | 安装 Pipeline Utility Steps 插件 |
| `MaskPasswordsBuildWrapper not found` | Mask Passwords 插件未安装 | 安装 Mask Passwords 插件 |
| `Modern SCM not supported` | Jenkins 版本过低 | 升级到 Jenkins 2.138+ |