The repository is the source of truth for both client and server modpack configuration. Packs are deployed through Gitea Actions and served as static Packwiz repositories for Pterodactyl.

Packs

Forever World

Long-lived NeoForge survival world with a deliberately conservative mod selection.

Minecraft: 1.21.1
NeoForge: 21.1.248
Packwiz: managed
Production: release-based

Development:

https://mc.ahmza.com/forever/dev/pack.toml

Stable:

https://mc.ahmza.com/forever/stable/pack.toml

Creative Playground Server

agsmc-playground is a disposable creative superflat server that consumes the Forever stable pack. It does not have an independent Packwiz publication channel. Upcoming pack changes are validated on agsmc-forever-staging through the Forever development endpoint.

Repository Structure

mc-modpacks/
├── .gitea/
│   └── workflows/
├── scripts/
│   └── build-site.sh
├── Dockerfile
├── sws.toml
├── forever/
│   ├── pack.toml
│   ├── index.toml
│   ├── mods/
│   ├── config/
│   ├── defaultconfigs/
│   └── README.md
└── deploy/
    └── kubernetes/

Development Model

main represents the current development state.

Normal changes are committed directly to main:

git switch main

cd forever
packwiz update <mod>
packwiz refresh

git add .
git commit -m "Update <mod>"
git push

A push to main publishes the pack to its dev endpoint.

Production is not updated by normal commits.

Branches

Branches are reserved for substantial or experimental work, for example:

mc-26-migration
create-major-upgrade
worldgen-experiment
test-new-content-mod

Small mod updates and configuration changes do not require branches.

Releases

Test the development pack before creating a release.

Forever World releases use annotated tags:

git tag -a forever-v1.0.1 -m "Forever World v1.0.1"
git push origin forever-v1.0.1

A release publishes an immutable copy to:

/forever/releases/v1.0.1/

and promotes the same build to:

/forever/stable/

Production Pterodactyl servers always consume the stable endpoint rather than individual release URLs.

Versioning

Approximately follow semantic versioning:

Version	Use
`v1.0.1`	Bug fixes, configs and routine mod updates
`v1.1.0`	New functionality or compatible mods
`v2.0.0`	Major Minecraft/modpack/world dependency changes

Release tags are immutable. Never move or recreate an existing release tag.

Deployment Flow

                         Gitea
                           │
                     push to main
                           │
                           ▼
                    Gitea Actions
                           │
                           ▼
                /forever/dev/pack.toml
                           │
                           ▼
                    Staging Server
                           │
                         Test
                           │
                  forever-v1.x.x tag
                           │
                           ▼
                    Gitea Actions
                      ┌────┴────┐
                      ▼         ▼
                  releases/   stable/
                                │
                                ▼
                         Production Server

Packwiz is responsible for modpack contents and side filtering.

Pterodactyl is responsible for Java, server process management and resources.

Kubernetes/SWS provides static hosting for the published Packwiz repositories. The publishing workflow runs scripts/build-site.sh, which exports committed Git revisions into the documented URL layout. Source packs intentionally keep no-internal-hashes = true; the workflow runs packwiz refresh --build only against the exported copies under .build/site so the image contains installer-ready hashes without committing generated hash churn. It then builds the multi-architecture image tea.ahmza.com/ahmza.com/mcpacks-site.

The workflow finally commits that image's immutable OCI digest to apps/mcpacks/deployment.yaml in the ahmza.com/k8s-starter-pack repository. Argo CD notices that commit and performs the rollout; the workflow does not hold Kubernetes credentials or change the cluster directly.

The publishing workflow uses two Gitea Actions repository secrets belonging to ci-bot:

REGISTRY_TOKEN can push packages owned by the ahmza.com organization
GITOPS_TOKEN can read and write ahmza.com/k8s-starter-pack

Keeping these credentials separate ensures that the package token cannot modify Git repositories and the GitOps token cannot publish packages.

The latest image tag exists only to bootstrap the first Argo CD sync and for human inspection. Normal rollouts use the exact content digest recorded in the GitOps manifest, making the running version auditable and rollback-friendly.

Rollback

Release directories are immutable.

If a release causes problems, production can be pointed temporarily at an earlier release:

https://mc.ahmza.com/forever/releases/v1.0.1/pack.toml

Do not rewrite an existing release or tag. Fix the issue on main and publish a new release.