Remote Exec Plugin (v2.0.10)

io.github.iuin8.remote is a Gradle plugin designed to simplify deployment pipelines by executing local and remote shell commands.

Features

• High Performance (v2.0.0): Fully compatible with Gradle Configuration Cache. Features lazy property resolution to significantly reduce build times for subsequent executions.
• Generalized YAML Parser: Robust stack-based YAML parser supporting complex nested structures, list-style environment definitions, and intelligent service_ports remapping.
• Production Safety: Smart confirmation prompts for production environments (prod).
• Clean Output: Optimized logging levels for a noise-free console experience.
• Environment Grouping: Tasks are automatically grouped by environment (e.g., remote-prod) to prevent list overload.
• Zero-Config SSH: Automatic SSH configuration and key management for project isolation.
• Robust Interaction (v2.0.1): Interactive tasks (Arthas/Debug) handle session terminations gracefully, preventing Gradle from crashing on exit.
• Jenkins Integration: Deep integration including user-triggered info and automated build logic.

Installation

Using the plugins DSL:

plugins {
  id "io.github.iuin8.remote" version "2.0.10"
}

Refer to the Gradle Plugin Portal for more details.

Basic Usage

Configuration

Define your configuration in a remote.yml file. You can find examples here:

• Example Project
• Example Configuration File

Usage

(See below for detailed configuration in Chinese, or refer to the source code for property definitions)

Chinese Documentation / 中文文档

SSH Configuration Management

The plugin supports automatic SSH configuration management, enabling out-of-the-box project-level SSH configurations.

Configuration File Location

Create an SSH configuration file in your project's plugin configuration directory:

<project-root>/gradle/remote-plugin/.ssh/config

Configuration Example

Host cloudflared.fa.internet.company
  HostName ssh-fa-ssy-edgeone-cn.iuin888vip.icu
  User root
  IdentityFile ~/.ssh/id_ed25519_iu
  ProxyCommand cloudflared access ssh --hostname %h --protocol quic

Auto-Injection Mechanism

When gradle/remote-plugin/.ssh/config exists in your project, the plugin automatically:

1. First Layer: System Configuration Injection

   • Adds plugin configuration reference at the beginning of ~/.ssh/config (first time only):

   # Auto-generated by Gradle Remote Plugin
   # DO NOT EDIT THIS BLOCK MANUALLY
   Include ~/.ssh/gradle/remote-plugin/config
   

2. Second Layer: Project Configuration Injection

   • Adds current project's configuration reference in ~/.ssh/gradle/remote-plugin/config:

   # Project: <project-name>
   # Path: <project-path>
   Include <project-root>/gradle/remote-plugin/.ssh/config
   

Configuration Structure

~/.ssh/config (System Config)
  ↓ Include
~/.ssh/gradle/remote-plugin/config (Plugin Managed Config)
  ↓ Include
  ├─ project1/gradle/remote-plugin/.ssh/config
  ├─ project2/gradle/remote-plugin/.ssh/config
  └─ projectN/gradle/remote-plugin/.ssh/config

Important Notes

⚠️ Avoid Host Name Conflicts

• SSH uses "first-match" principle - stops at the first matching Host
• Don't configure duplicate Host names across different projects' .ssh/config files
• When Host name conflicts occur, only the first matched configuration takes effect
• Project configurations have higher priority than subsequent definitions in system config

6. Environment Variables and Local Overrides (v1.4.3+)

For secure management of sensitive information (e.g., Jenkins Tokens), the plugin supports:

• Placeholder Substitution: Use ${MY_TOKEN} in remote.yml, and the plugin will automatically resolve it from environment variables or Gradle project properties.
• Local Override File: Create remote-local.yml in the same directory to override configurations in remote.yml. Highly recommended to add this file to your .gitignore.

7. Version Control Recommendations

• remote.yml: Recommended to include in Git for team sharing
• remote-local.yml: Strongly recommended to add to .gitignore for secrets
• .ssh/config: Choose based on your needs
  • If it contains sensitive information (private hosts, usernames), add to .gitignore
  • If it's generic configuration (like bastion hosts), can be version controlled

Configuration Management Benefits

• ✅ Project-level configuration, isolated between projects
• ✅ Automatic injection, no manual system config editing
• ✅ Centralized management, unified maintenance
• ✅ Out-of-the-box, works immediately after cloning