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:

plugins/gitpull/config.yml

Example configuration:

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

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

  devpack:
    repository: "[https://github.com/example/repo.git](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:

git-command: git

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

git-command: "/bin/git"

clone-if-missing

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

clone-if-missing: true

timeout-seconds

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

timeout-seconds: 300

Repository Configuration Items

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

For example:

repositories:
  example:
    repository: "[https://github.com/example/repo.git](https://github.com/example/repo.git)"
    directory: "world/datapacks/repo"
    branch: "master"

repository

The remote repository URL.

HTTPS is supported:

repository: "[https://github.com/username/repo.git](https://github.com/username/repo.git)"

SSH is also supported:

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:

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.

branch: "master"

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

branch: ""

Usage Examples

Pull All Repositories

/pull

Pull a Single Repository

/pull autoop

Reload Configuration

/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:

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:

repository: "[https://username:yourtoken@github.com/username/repo.git](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.