Skip to content

Commit 1b6fa02

Browse files
fdevansfdevans
committed
docs: comprehensive README improvements for authentication and Key Storage
- Added detailed step-by-step setup instructions for Key Storage - Added example Key Storage paths for different scenarios - Created authentication examples table by Git URL type - Added comprehensive troubleshooting section for common issues - Added security best practices section - Added Quick Reference section with: - Key Storage setup instructions - Common configuration scenarios (GitHub, GitLab, HTTPS, SSH) - Property reference table - Version requirements - Improved workflow steps authentication documentation - Organized content with clear sections and examples README expanded from 175 to 344 lines with actionable guidance.
1 parent 1ff647d commit 1b6fa02

1 file changed

Lines changed: 187 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 187 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -54,25 +54,111 @@ You need to set up the following options to use the plugin:
5454

5555
### Authentication
5656

57-
The plugin supports multiple authentication methods:
57+
The plugin supports multiple authentication methods. **Key Storage is recommended** for secure credential management.
5858

5959
#### Password Authentication
60-
* **Git Password (Plain Text)**: Password to authenticate remotely (plain text - less secure)
61-
* **Git Password Storage Path**: Key storage path for Git password (more secure - recommended)
6260

63-
If both password fields are configured, the Key Storage path takes precedence for security.
61+
##### Option 1: Key Storage (Recommended)
62+
* **Git Password Storage Path**: Key storage path for Git password (secure)
63+
64+
**How to use:**
65+
1. Navigate to Rundeck **System Menu** → **Key Storage**
66+
2. Click **Add or Upload a Key** → **Password**
67+
3. Enter a path like `keys/git/myrepo-password` and your Git password
68+
4. In the Resource Model configuration, use the **Key Storage browser** to select the password path
69+
70+
**Example paths:**
71+
```
72+
keys/git/github-token # GitHub personal access token
73+
keys/git/gitlab-password # GitLab password
74+
keys/project1/git-auth # Project-specific credentials
75+
```
76+
77+
##### Option 2: Plain Text (Less Secure)
78+
* **Git Password (Plain Text)**: Password to authenticate remotely (not recommended for production)
79+
80+
**Note:** If both are configured, Key Storage takes precedence.
81+
82+
---
6483

6584
#### SSH Key Authentication
66-
* **SSH: Strict Host Key Checking**: Use strict host key checking.
67-
If `yes`, require remote host SSH key is defined in the `~/.ssh/known_hosts` file, otherwise do not verify.
68-
* **SSH Key Path (Filesystem)**: SSH Key Path from filesystem to authenticate
69-
* **SSH Key Storage Path**: SSH Key storage path from Rundeck Key Storage (more secure - recommended)
7085

71-
If both SSH key fields are configured, the Key Storage path takes precedence for security.
86+
##### Option 1: Key Storage (Recommended)
87+
* **SSH Key Storage Path**: SSH Key from Rundeck Key Storage (secure)
88+
89+
**How to use:**
90+
1. Navigate to Rundeck **System Menu** → **Key Storage**
91+
2. Click **Add or Upload a Key** → **Private Key**
92+
3. Upload your SSH private key (e.g., `id_rsa`) and save it with a path like `keys/git/ssh-key`
93+
4. In the Resource Model configuration, use the **Key Storage browser** to select the key path
94+
95+
**Example paths:**
96+
```
97+
keys/git/deployment-key # Deployment key for specific repo
98+
keys/git/github-ssh-key # GitHub SSH key
99+
keys/shared/git-readonly-key # Shared read-only access key
100+
```
101+
102+
##### Option 2: Filesystem Path (Legacy)
103+
* **SSH Key Path (Filesystem)**: Path to SSH key file on the Rundeck server filesystem
104+
105+
**Example:** `/home/rundeck/.ssh/id_rsa`
106+
107+
**Note:** If both are configured, Key Storage takes precedence.
108+
109+
##### SSH Host Key Checking
110+
* **SSH: Strict Host Key Checking**:
111+
- `yes` - Require remote host SSH key is defined in `~/.ssh/known_hosts` (more secure)
112+
- `no` - Skip host key verification (less secure, useful for testing)
113+
114+
---
115+
116+
#### Authentication Examples by Git URL Type
117+
118+
| Git URL Type | Recommended Auth | Example URL |
119+
|--------------|------------------|-------------|
120+
| HTTPS with token | Password Storage (token) | `https://github.com/user/repo.git` |
121+
| HTTPS with password | Password Storage | `https://username@github.com/user/repo.git` |
122+
| SSH | SSH Key Storage | `git@github.com:user/repo.git` |
123+
| SSH | SSH Key Storage | `ssh://git@github.com/user/repo.git` |
124+
125+
**Important:** For HTTPS authentication, include the username in the URL: `https://username@host.com/repo.git`
126+
127+
---
128+
129+
#### Troubleshooting Authentication
130+
131+
**Problem: "Authentication failed" error**
132+
- Verify the Key Storage path is correct (e.g., `keys/git/password`, not `/keys/git/password`)
133+
- Ensure the credential exists in Key Storage
134+
- For HTTPS: Include username in Git URL (`https://user@github.com/...`)
135+
- For SSH: Verify host key is in `known_hosts` if strict checking is enabled
136+
137+
**Problem: "storageTree is null" in logs**
138+
- The plugin requires Services API (Rundeck 5.16.0+)
139+
- Fallback to filesystem/plain text options if Key Storage is unavailable
140+
141+
**Problem: SSH authentication fails**
142+
- Verify SSH key format (OpenSSH format, starts with `-----BEGIN RSA PRIVATE KEY-----` or similar)
143+
- Check SSH key permissions if using filesystem path (should be `600`)
144+
- For GitHub/GitLab, ensure the public key is added to your account
145+
- Try with `Strict Host Key Checking = no` for initial testing
146+
147+
**Problem: Key Storage path not found**
148+
- Key Storage paths should start with `keys/` (e.g., `keys/git/password`)
149+
- Use the Key Storage browser in the UI to select the correct path
150+
- Verify the key type matches (password vs private key)
151+
152+
---
153+
154+
#### Security Best Practices
72155

73-
**Recommended:** Use Key Storage for credentials instead of plain text or filesystem paths. To use Key Storage:
74-
1. Store your password or SSH key in Rundeck Key Storage (under `keys/` path)
75-
2. Select the credential path using the Key Storage browser in the plugin configuration
156+
1. **Always use Key Storage** in production environments
157+
2. **Use project-specific keys** when possible (e.g., `keys/project1/git-key`)
158+
3. **Use deployment keys** with minimal permissions for SSH
159+
4. **Use personal access tokens** instead of passwords for HTTPS (GitHub, GitLab, etc.)
160+
5. **Rotate credentials regularly** and update them in Key Storage
161+
6. **Enable strict host key checking** for SSH in production
76162

77163
### Limitations
78164

@@ -101,10 +187,17 @@ This plugin can clone/pull, add, commit, and push a git repository via 4 Workflo
101187

102188
##### Authentication
103189

104-
* **Password Storage Path**: Password storage path to authenticate remotely. This can be an Access Token - such as a Github access token.
105-
* **SSH: Strict Host Key Checking**: Use strict host key checking.
106-
If `yes`, require remote host SSH key is defined in the `~/.ssh/known_hosts` file, otherwise do not verify.
107-
* **SSH Key Storage Path**: SSH Key storage path to authenticate
190+
The workflow steps support the same authentication methods as the Resource Model:
191+
192+
* **Password Storage Path**: Key Storage path for Git password or access token (e.g., `keys/git/github-token`)
193+
* **SSH Key Storage Path**: Key Storage path for SSH private key (e.g., `keys/git/ssh-key`)
194+
* **SSH: Strict Host Key Checking**:
195+
- `yes` - Require host key in `~/.ssh/known_hosts` (recommended for production)
196+
- `no` - Skip host key verification (useful for testing)
197+
198+
**Tip:** You can use GitHub/GitLab personal access tokens as passwords for HTTPS authentication.
199+
200+
For detailed authentication setup and troubleshooting, see the [Authentication section](#authentication) above.
108201

109202
### GIT Clone Workflow Step
110203

@@ -172,4 +265,81 @@ You need to set up following additional options to use the plugin:
172265

173266
* **Message**: Commit message to be used. Defaults to `Rundeck Commit`
174267
* **Add**: Adds all contents of the git repo before commiting. Defaults to `False`. If you need to be more specific, please use `GIT / Add` workflow step.
175-
* **Push**: Pushes the repository after commiting the changes. Defaults to `False`.
268+
* **Push**: Pushes the repository after commiting the changes. Defaults to `False`.
269+
270+
---
271+
272+
## Quick Reference
273+
274+
### Key Storage Setup
275+
276+
**For Passwords/Tokens:**
277+
1. System Menu → Key Storage → Add or Upload a Key → **Password**
278+
2. Path format: `keys/git/your-credential-name`
279+
3. Select in plugin using Key Storage browser
280+
281+
**For SSH Keys:**
282+
1. System Menu → Key Storage → Add or Upload a Key → **Private Key**
283+
2. Upload your private key file (e.g., `id_rsa`)
284+
3. Path format: `keys/git/your-key-name`
285+
4. Select in plugin using Key Storage browser
286+
287+
### Common Configuration Scenarios
288+
289+
#### Scenario 1: Public GitHub Repo (Read-Only)
290+
```
291+
Git URL: https://github.com/user/repo.git
292+
Branch: main
293+
Authentication: None required
294+
```
295+
296+
#### Scenario 2: Private GitHub Repo with Personal Access Token
297+
```
298+
Git URL: https://github.com/user/repo.git
299+
Branch: main
300+
Authentication: Git Password Storage Path → keys/git/github-token
301+
(Store GitHub PAT in Key Storage as password)
302+
```
303+
304+
#### Scenario 3: Private GitLab Repo with SSH Key
305+
```
306+
Git URL: git@gitlab.com:user/repo.git
307+
Branch: main
308+
Authentication: SSH Key Storage Path → keys/git/gitlab-ssh-key
309+
Strict Host Key Checking: yes
310+
```
311+
312+
#### Scenario 4: Private Repo with HTTPS Username/Password
313+
```
314+
Git URL: https://username@github.com/user/repo.git
315+
Branch: main
316+
Authentication: Git Password Storage Path → keys/git/password
317+
(Include username in URL)
318+
```
319+
320+
### Property Reference
321+
322+
| Property Name | Description | Example Value |
323+
|--------------|-------------|---------------|
324+
| `gitUrl` | Git repository URL | `https://github.com/user/repo.git` |
325+
| `gitBaseDirectory` | Local checkout directory | `/var/rundeck/git-repos/project1` |
326+
| `gitBranch` | Branch to checkout | `main` or `develop` |
327+
| `gitFile` | Resource model file in repo | `resources.yaml` |
328+
| `gitFormatFile` | File format | `xml`, `yaml`, or `json` |
329+
| `gitPasswordPath` | Plain text password | `mypassword` (not recommended) |
330+
| `gitPasswordPathStorage` | Key Storage path for password | `keys/git/password` |
331+
| `gitKeyPath` | Filesystem SSH key path | `/home/rundeck/.ssh/id_rsa` |
332+
| `gitKeyPathStorage` | Key Storage path for SSH key | `keys/git/ssh-key` |
333+
| `strictHostKeyChecking` | SSH host key verification | `yes` or `no` |
334+
| `writable` | Allow writing to remote | `true` or `false` |
335+
336+
### Version Requirements
337+
338+
- **Rundeck 5.16.0 or later** - Required for Key Storage support
339+
- Earlier versions can use filesystem paths and plain text authentication
340+
341+
### Support
342+
343+
For issues or questions:
344+
- GitHub Issues: [rundeck-plugins/git-plugin](https://github.com/rundeck-plugins/git-plugin/issues)
345+
- Rundeck Documentation: [https://docs.rundeck.com](https://docs.rundeck.com)

0 commit comments

Comments
 (0)