# How to Set Up CI/CD for the Pumpkin-MC/Pumpkin Project: GitHub Actions and Docker Pipeline

> Automate Rust Minecraft server builds for Pumpkin MC/Pumpkin with GitHub Actions and Docker. Learn to set up CI/CD for automated testing and containerized deployment.

- Repository: [Pumpkin MC/Pumpkin](https://github.com/Pumpkin-MC/Pumpkin)
- Tags: how-to-guide
- Published: 2026-07-23

---

**The Pumpkin-MC/Pumpkin project automates its Rust Minecraft server builds using GitHub Actions for continuous integration and Docker for continuous delivery, enabling automated testing, linting, and containerized deployment.**

Pumpkin is a Rust-based Minecraft server implementation that leverages a comprehensive CI/CD pipeline to ensure code quality and streamline releases. The project uses **GitHub Actions** to orchestrate the build process and **Docker** for packaging and deployment. This guide explains how to configure and understand the pipeline using the actual workflow definitions and deployment files from the repository.

## Understanding the CI/CD Architecture

The continuous integration pipeline for Pumpkin is defined in [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml). This workflow orchestrates multiple stages including code formatting checks, static analysis, test execution, binary compilation, and container image publishing. The pipeline triggers on every push and pull request targeting the `master` branch, running on the latest Ubuntu runner.

The workflow integrates with several key configuration files:

- [`rust-toolchain.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/rust-toolchain.toml) specifies the exact Rust version for reproducible builds
- `Dockerfile` defines the multi-stage container build process
- [`docker-compose.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/docker-compose.yml) provides production deployment orchestration
- `flake.nix` enables reproducible builds for Nix users

## Configuring the GitHub Actions Workflow

The core CI logic resides in [`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml). While the file is located in the hidden `.github` directory, its structure follows standard Rust CI patterns with Pumpkin-specific deployment steps.

### Workflow Triggers and Environment

The pipeline activates on Git events targeting the `master` branch:

```yaml
name: Rust CI
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

```

### Rust Toolchain Setup and Caching

The workflow installs the Rust toolchain specified in [`rust-toolchain.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/rust-toolchain.toml) using `rustup`. To optimize build times, the configuration caches the Cargo registry and git dependencies:

```yaml
      - name: Cache cargo registry
        uses: actions/cache@v3
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

```

This caching strategy stores `~/.cargo/registry` and `~/.cargo/git` between workflow runs, significantly reducing dependency resolution time for subsequent builds.

### Code Quality Gates

The CI enforces strict code quality through automated formatting and linting checks. The workflow runs `cargo fmt -- --check` to verify code style compliance and executes `cargo clippy -- -D warnings` to catch potential bugs and enforce Rust best practices.

These checks prevent code that fails formatting or contains Clippy warnings from merging into the master branch, maintaining consistent code quality across the `pumpkin-*` crate workspace.

### Testing and Release Builds

After passing quality gates, the workflow executes the full test suite:

```yaml
      - name: Run tests
        run: cargo test --all-features

```

The tests cover world loading, packet handling, and plugin interfaces across all workspace crates. Following successful tests, the pipeline builds release binaries using `cargo build --release` for both the native target and `x86_64-unknown-linux-musl` (used by the Docker image).

## Containerization and Deployment Strategy

Pumpkin uses a multi-stage Docker build to create minimal production images. The CI pipeline automatically builds and publishes these images to Docker Hub.

### Building the Docker Image

The workflow constructs the container image using the repository's `Dockerfile`, which performs a multi-stage build copying the stripped binary into an Alpine Linux base image:

```yaml
      - name: Build Docker image
        run: |
          docker build -t pumpkinmc/pumpkin:${{ github.sha }} .

```

This creates an image tagged with the Git commit SHA, ensuring traceability between code versions and deployed artifacts.

### Configuring Docker Hub Authentication

To push images to Docker Hub, the workflow uses repository secrets configured in the GitHub settings:

```yaml
      - name: Push Docker image
        if: github.ref == 'refs/heads/master'
        run: |
          echo "${{ secrets.DOCKERHUB_TOKEN }}" | docker login -u "${{ secrets.DOCKERHUB_USER }}" --password-stdin
          docker push pumpkinmc/pumpkin:${{ github.sha }}

```

The `DOCKERHUB_USER` and `DOCKERHUB_TOKEN` secrets are never exposed in the codebase and are only accessible to the CI environment during master branch builds.

### Deploying with Docker Compose

The repository includes a [`docker-compose.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/docker-compose.yml) file that simplifies production deployment. After the CI pipeline publishes a new image, deploy the server using:

```bash
docker compose up -d

```

This command pulls the latest image and starts the Pumpkin server with the correct volume mounts and port configurations defined in the compose file.

### Nix Flake Integration

For users preferring reproducible builds without Docker, the `flake.nix` file provides a Nix-based development environment. Enter the development shell and run the server with:

```bash
nix develop
cargo run --release

```

This approach ensures the exact Rust toolchain and dependencies specified in the lock files are available without installing system-wide dependencies.

## Local CI Testing and Validation

Before pushing changes, you can validate the CI steps locally to ensure builds will pass. Run the formatting check with `cargo fmt -- --check`, execute `cargo clippy -- -D warnings` for linting, and verify tests with `cargo test --all-features`.

For Docker validation, build the image locally using `docker build -t pumpkin-local .` and test the container startup to verify the multi-stage build process defined in the `Dockerfile` completes successfully.

## Summary

- The **[`.github/workflows/rust.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/.github/workflows/rust.yml)** file defines the complete CI/CD pipeline, triggering on pushes and pull requests to the `master` branch.
- **[`rust-toolchain.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/rust-toolchain.toml)** pins the Rust version, while the workflow caches `~/.cargo/registry` and `~/.cargo/git` to accelerate builds.
- The pipeline enforces code quality through **`cargo fmt`** and **`cargo clippy`** checks before executing **`cargo test --all-features`**.
- **Docker** images are built using the multi-stage **`Dockerfile`** and pushed to Docker Hub using repository secrets (`DOCKERHUB_TOKEN` and `DOCKERHUB_USER`).
- Production deployment is streamlined via **[`docker-compose.yml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/docker-compose.yml)**, with an alternative **`flake.nix`** available for Nix-based workflows.

## Frequently Asked Questions

### What Rust version does the Pumpkin CI/CD pipeline use?

The pipeline uses the Rust version specified in **[`rust-toolchain.toml`](https://github.com/Pumpkin-MC/Pumpkin/blob/main/rust-toolchain.toml)**, ensuring all CI builds and local development use identical compiler versions. The GitHub Actions workflow installs this specific toolchain via `rustup` at the start of each run.

### How does the CI handle Cargo dependencies between workflow runs?

The workflow uses **`actions/cache@v3`** to persist the `~/.cargo/registry` and `~/.cargo/git` directories between runs. This cache is keyed by the runner operating system and the hash of `Cargo.lock`, ensuring dependencies are only downloaded when the lock file changes.

### Can I deploy the Pumpkin server without using Docker?

Yes, you can deploy using the **`flake.nix`** file for a reproducible Nix-based build, or manually compile the release binary with `cargo build --release` and run it directly. However, Docker is the primary deployment method supported by the automated CI/CD pipeline.

### Where do I configure the Docker Hub credentials for automated image pushes?

Docker Hub authentication is configured in the GitHub repository settings under **Secrets and variables > Actions**. Add `DOCKERHUB_USER` for your Docker Hub username and `DOCKERHUB_TOKEN` for an access token. The workflow references these in the push step using `${{ secrets.DOCKERHUB_USER }}` and `${{ secrets.DOCKERHUB_TOKEN }}`.