gitpull

GitPull

A plugin for Spigot/Paper servers, used to execute pull operations from Git repositories.

Supported Features:

- `/pull`: Pulls all configured repositories. - `/pull <name>`: Pulls a specified repository. - `/pull reload`: Reloads the configuration file. - Supports pulling multiple repositories into different directories respectively. - Supports execution by OP (Server Operator) and the server console. - Supports Tab completion for repository names and `reload`.

Installation

1. Place the plugin jar file into the server's `plugins` directory. 2. Start the server once to generate the default configuration file. 3. Edit `plugins/gitpull/config.yml`. 4. Execute `/pull reload` to reload the configuration, or restart the server directly.

Commands

`/pull`

Pulls all repositories defined in the configuration file.

`/pull <name>`

Pulls the repository with the specified name.

`/pull reload`

Reloads the plugin configuration file.

Permissions

- `gitpull.pull`: Allows the execution of `/pull` and `/pull <name>`. - `gitpull.reload`: Allows the execution of `/pull reload`.

By default, both permissions are granted to `op`.

Configuration File

Configuration file path:

```text plugins/gitpull/config.yml ```

Example configuration:

```yml git-command: git clone-if-missing: true timeout-seconds: 300

repositories: autoop: repository: "https://github.com/example/repo.git" directory: "world/datapacks/repo" branch: "master"

devpack: repository: "https://github.com/example/repo.git" directory: "world/datapacks/dev" branch: "dev" ```

Global Configuration Items

`git-command`

The Git command to be invoked. Default is:

```yml git-command: git ```

If the `git` executable cannot be found in the server's environment variables, an absolute path can be provided, for example:

```yml git-command: "/bin/git" ```

`clone-if-missing`

Whether to automatically execute `git clone` when the target directory is not a valid Git repository.

```yml clone-if-missing: true ```

`timeout-seconds`

The timeout duration for a single repository operation, in seconds.

```yml timeout-seconds: 300 ```

Repository Configuration Items

Each repository is defined under `repositories` and is distinguished by a unique name.

For example:

```yml repositories: example: repository: "https://github.com/example/repo.git" directory: "world/datapacks/repo" branch: "master" ```

`repository`

The remote repository URL.

HTTPS is supported:

```yml repository: "https://github.com/username/repo.git" ```

SSH is also supported:

```yml repository: "git@github.com:username/repo.git" ```

`directory`

The local target directory for pulling.

- Absolute path: Uses the provided path directly. - Relative path: Resolved relative to the server root directory.

For example:

```yml directory: "world/datapacks/AutoOP" ```

This will pull the data to `world/datapacks/AutoOP` under the server root directory.

`branch`

The branch to pull or clone. This field can be empty.

```yml branch: "master" ```

If left empty, the repository's default branch will be used:

```yml branch: "" ```

Usage Examples

Pull All Repositories

```text /pull ```

Pull a Single Repository

```text /pull autoop ```

Reload Configuration

```text /pull reload ```

Private Repositories

This plugin invokes the `git` executable on the server system, meaning private repository authentication relies strictly on the server machine's local Git configuration.

Recommended methods:

1. SSH Key

Format the repository URL as:

```yml repository: "git@github.com:username/private-repo.git" ```

Then, configure an SSH key on the server machine and add the corresponding public key to your GitHub account or to the repository's Deploy Keys.

2. Git Credential Manager

If using HTTPS, you can manually execute a Git login operation once on the server machine to let the system remember the credentials. The plugin will then reuse them.

It is highly unrecommended to write the token directly in plain text within the configuration file:

```yml repository: "https://username:yourtoken@github.com/username/repo.git" ```

Notes

- Repository names cannot be named `reload`. - When `/pull` is executed for all repositories, they will be processed sequentially in the configured order. - If a specific repository fails, it will not prevent subsequent repositories from executing. - If a pull task is already running, any new `/pull` requests will be rejected. - If the target directory already exists, is not a Git repository, and is not empty, the plugin will not forcefully overwrite the directory.

Logging Information

- Upon success, a success message will be displayed in the in-game chat or the server console. - Detailed `git stdout` (Standard Output) and `git stderr` (Standard Error) will be output to the server logs. - After a batch pull is completed, the total number of successes and failures will be displayed.