mirror of
https://github.com/appleboy/drone-jenkins.git
synced 2026-06-04 10:15:02 +08:00
docs: document and standardize multi-line build parameter configurations
- Add example configurations for build parameters and waiting for job completion - Document new settings: wait, poll_interval, timeout, insecure, and remote_token - Update parameters format to require multi-line key=value pairs (one per line) - Clarify handling of whitespace, empty lines, and multiple equals signs in parameter values - Revise CLI and Docker usage examples to use multi-line parameters format - Update YAML configuration example to use multi-line parameters block Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>
This commit is contained in:
Bo-Yi Wu
@@ -48,6 +48,37 @@ Example configuration with jobs in the folder:
|
||||
|
||||
It will trigger the URL of Jenkins job like as `http://example.com/job/folder_name/job/job_name/`
|
||||
|
||||
Example configuration with build parameters:
|
||||
|
||||
```yaml
|
||||
- name: trigger jenkins job
|
||||
image: appleboy/drone-jenkins
|
||||
settings:
|
||||
url: http://example.com
|
||||
user: appleboy
|
||||
token: xxxxxxxxxx
|
||||
job: parameterized-job
|
||||
parameters: |
|
||||
ENVIRONMENT=production
|
||||
VERSION=${DRONE_TAG}
|
||||
COMMIT_SHA=${DRONE_COMMIT_SHA}
|
||||
```
|
||||
|
||||
Example configuration with wait for completion:
|
||||
|
||||
```yaml
|
||||
- name: trigger jenkins job and wait
|
||||
image: appleboy/drone-jenkins
|
||||
settings:
|
||||
url: http://example.com
|
||||
user: appleboy
|
||||
token: xxxxxxxxxx
|
||||
job: deploy-job
|
||||
wait: true
|
||||
poll_interval: 15s
|
||||
timeout: 1h
|
||||
```
|
||||
|
||||
## Parameter Reference
|
||||
|
||||
url
|
||||
@@ -61,3 +92,21 @@ token
|
||||
|
||||
job
|
||||
: jenkins job name
|
||||
|
||||
parameters
|
||||
: build parameters in multi-line `key=value` format (one per line)
|
||||
|
||||
wait
|
||||
: wait for job completion (default: false)
|
||||
|
||||
poll_interval
|
||||
: interval between status checks when waiting (default: 10s)
|
||||
|
||||
timeout
|
||||
: maximum time to wait for job completion (default: 30m)
|
||||
|
||||
insecure
|
||||
: allow insecure SSL connections (default: false)
|
||||
|
||||
remote_token
|
||||
: jenkins remote trigger token (alternative to user/token authentication)
|
||||
|
||||
@@ -117,24 +117,34 @@ Alternatively, you can use a remote trigger token configured in your Jenkins job
|
||||
|
||||
### Parameters Reference
|
||||
|
||||
| Parameter | CLI Flag | Environment Variable | Required | Description |
|
||||
| ------------- | -------------------- | ----------------------------------------------- | ------------- | ------------------------------------------------------ |
|
||||
| Host | `--host` | `PLUGIN_URL`, `JENKINS_URL` | Yes | Jenkins base URL (e.g., `http://jenkins.example.com/`) |
|
||||
| User | `--user`, `-u` | `PLUGIN_USER`, `JENKINS_USER` | Conditional\* | Jenkins username |
|
||||
| Token | `--token`, `-t` | `PLUGIN_TOKEN`, `JENKINS_TOKEN` | Conditional\* | Jenkins API token |
|
||||
| Remote Token | `--remote-token` | `PLUGIN_REMOTE_TOKEN`, `JENKINS_REMOTE_TOKEN` | Conditional\* | Jenkins remote trigger token |
|
||||
| Job | `--job`, `-j` | `PLUGIN_JOB`, `JENKINS_JOB` | Yes | Jenkins job name(s) - can specify multiple |
|
||||
| Parameters | `--parameters`, `-p` | `PLUGIN_PARAMETERS`, `JENKINS_PARAMETERS` | No | Build parameters in `key=value` format |
|
||||
| Insecure | `--insecure` | `PLUGIN_INSECURE`, `JENKINS_INSECURE` | No | Allow insecure SSL connections (default: false) |
|
||||
| Wait | `--wait` | `PLUGIN_WAIT`, `JENKINS_WAIT` | No | Wait for job completion (default: false) |
|
||||
| Poll Interval | `--poll-interval` | `PLUGIN_POLL_INTERVAL`, `JENKINS_POLL_INTERVAL` | No | Interval between status checks (default: 10s) |
|
||||
| Timeout | `--timeout` | `PLUGIN_TIMEOUT`, `JENKINS_TIMEOUT` | No | Maximum time to wait for job completion (default: 30m) |
|
||||
| Parameter | CLI Flag | Environment Variable | Required | Description |
|
||||
| ------------- | -------------------- | ----------------------------------------------- | ------------- | ----------------------------------------------------------------- |
|
||||
| Host | `--host` | `PLUGIN_URL`, `JENKINS_URL` | Yes | Jenkins base URL (e.g., `http://jenkins.example.com/`) |
|
||||
| User | `--user`, `-u` | `PLUGIN_USER`, `JENKINS_USER` | Conditional\* | Jenkins username |
|
||||
| Token | `--token`, `-t` | `PLUGIN_TOKEN`, `JENKINS_TOKEN` | Conditional\* | Jenkins API token |
|
||||
| Remote Token | `--remote-token` | `PLUGIN_REMOTE_TOKEN`, `JENKINS_REMOTE_TOKEN` | Conditional\* | Jenkins remote trigger token |
|
||||
| Job | `--job`, `-j` | `PLUGIN_JOB`, `JENKINS_JOB` | Yes | Jenkins job name(s) - can specify multiple |
|
||||
| Parameters | `--parameters`, `-p` | `PLUGIN_PARAMETERS`, `JENKINS_PARAMETERS` | No | Build parameters in multi-line `key=value` format (one per line) |
|
||||
| Insecure | `--insecure` | `PLUGIN_INSECURE`, `JENKINS_INSECURE` | No | Allow insecure SSL connections (default: false) |
|
||||
| Wait | `--wait` | `PLUGIN_WAIT`, `JENKINS_WAIT` | No | Wait for job completion (default: false) |
|
||||
| Poll Interval | `--poll-interval` | `PLUGIN_POLL_INTERVAL`, `JENKINS_POLL_INTERVAL` | No | Interval between status checks (default: 10s) |
|
||||
| Timeout | `--timeout` | `PLUGIN_TIMEOUT`, `JENKINS_TIMEOUT` | No | Maximum time to wait for job completion (default: 30m) |
|
||||
|
||||
**Authentication Requirements**: You must provide either:
|
||||
|
||||
- `user` + `token` (API token authentication), OR
|
||||
- `remote-token` (remote trigger token authentication)
|
||||
|
||||
**Parameters Format**: The `parameters` field accepts a multi-line string where each line contains one `key=value` pair:
|
||||
|
||||
- Each parameter should be on a separate line
|
||||
- Format: `KEY=VALUE` (one per line)
|
||||
- Empty lines are automatically ignored
|
||||
- Whitespace-only lines are skipped
|
||||
- Keys are trimmed of surrounding whitespace
|
||||
- Values preserve intentional spaces
|
||||
- Values can contain `=` signs (everything after the first `=` is treated as the value)
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Line
|
||||
@@ -168,8 +178,21 @@ drone-jenkins \
|
||||
--user appleboy \
|
||||
--token XXXXXXXX \
|
||||
--job my-jenkins-job \
|
||||
--parameters "ENVIRONMENT=production" \
|
||||
--parameters "VERSION=1.0.0"
|
||||
--parameters $'ENVIRONMENT=production\nVERSION=1.0.0'
|
||||
```
|
||||
|
||||
Or using environment variable:
|
||||
|
||||
```bash
|
||||
export JENKINS_PARAMETERS="ENVIRONMENT=production
|
||||
VERSION=1.0.0
|
||||
BRANCH=main"
|
||||
|
||||
drone-jenkins \
|
||||
--host http://jenkins.example.com/ \
|
||||
--user appleboy \
|
||||
--token XXXXXXXX \
|
||||
--job my-jenkins-job
|
||||
```
|
||||
|
||||
**Using remote token authentication:**
|
||||
@@ -226,7 +249,7 @@ docker run --rm \
|
||||
-e JENKINS_USER=appleboy \
|
||||
-e JENKINS_TOKEN=xxxxxxx \
|
||||
-e JENKINS_JOB=my-jenkins-job \
|
||||
-e JENKINS_PARAMETERS="ENVIRONMENT=production,VERSION=1.0.0" \
|
||||
-e JENKINS_PARAMETERS=$'ENVIRONMENT=production\nVERSION=1.0.0\nBRANCH=main' \
|
||||
ghcr.io/appleboy/drone-jenkins
|
||||
```
|
||||
|
||||
@@ -277,10 +300,11 @@ steps:
|
||||
job:
|
||||
- deploy-frontend
|
||||
- deploy-backend
|
||||
parameters:
|
||||
- ENVIRONMENT=production
|
||||
- VERSION=${DRONE_TAG}
|
||||
- COMMIT_SHA=${DRONE_COMMIT_SHA}
|
||||
parameters: |
|
||||
ENVIRONMENT=production
|
||||
VERSION=${DRONE_TAG}
|
||||
COMMIT_SHA=${DRONE_COMMIT_SHA}
|
||||
BRANCH=${DRONE_BRANCH}
|
||||
```
|
||||
|
||||
**Using remote token:**
|
||||
|
||||
Reference in New Issue
Block a user