# axolotl-pm/pmmp-plugin-actions architecture

> Architecture diagram of the GitHub repository axolotl-pm/pmmp-plugin-actions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/axolotl-pm/pmmp-plugin-actions
- Repository: https://github.com/axolotl-pm/pmmp-plugin-actions

## Overview

#### Purpose and Entry Points
This repository is a reusable GitHub Actions package for PocketMine-MP plugin delivery. Its public entry points are four composite actions, each exposed through its action manifest:
- `build-phar/action.yml`
- `validate-release/action.yml`
- `publish-release/action.yml`
- `publish-nightly/action.yml`

Consumer repositories invoke these actions in their own workflows after checkout; this repository does not host or run a plugin itself.

#### Build and Artifact Stage
`build-phar/action.yml` is the central production stage. It provisions a requested PHP runtime, reads plugin metadata from the consumer checkout’s `plugin.yml`, packages/compresses the plugin into a PHAR, and uploads it as a GitHub Actions artifact.

Its interface carries metadata across job boundaries: plugin name, plugin version, PocketMine-MP API version, artifact name, PHAR path, and staging directory. Inputs define packaging boundaries, including plugin directory, Composer inclusion/version, extra sources/assets, artifact retention, and optional Poggit staging.

#### Release Validation Gate
`validate-release/action.yml` is a pass/fail gate for tag-triggered releases. It compares the pushed Git tag against the plugin version declared in `plugin.yml`, normalizing a leading `v` and prerelease suffixes before comparison.

This action must execute after `actions/checkout` in the caller’s job and should precede `build-phar` in a release workflow. It prevents publishing a binary whose declared plugin version does not match the release tag.

#### Stable Release Publication
`publish-release/action.yml` consumes the artifact identifier and build metadata emitted by `build-phar`. It downloads the uploaded PHAR and creates a GitHub Release, attaching the binary and deriving prerelease status from tags containing `-`.

The boundary between build and publication is GitHub Actions artifact storage: callers must explicitly promote composite-action outputs to job outputs, then pass them to the publishing job. Publishing requires `contents: write`; checkout is not required for this stage.

#### Nightly Publication
`publish-nightly/action.yml` implements the mutable development-release path. It consumes the same build artifact and metadata, force-updates the `nightly` tag to a selected commit SHA, then creates or updates a nightly prerelease with timestamped/version-aware release information.

Unlike stable publishing, this action needs the caller checkout because it moves a Git ref. It also requires `contents: write`. The mutable tag is the key control boundary separating nightly outputs from immutable version-tag releases.

#### Runtime, Infrastructure, and External Services
All behavior runs as GitHub Actions composite actions on caller-selected runners, typically `ubuntu-latest`. Key infrastructure dependencies are GitHub checkout, artifact upload/download, Git refs/tags, and GitHub Releases.

The build path depends on PHP binaries available through `pmmp/PHP-Binaries`, Composer when enabled, and the PocketMine-MP plugin format/API metadata. Optional staging integrates with Poggit CI. Repository-local quality automation is defined at `.github/workflows/linter.yml`.

Main entry points: [`build-phar/action.yml`](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/build-phar/action.yml) (Build PHAR), [`publish-nightly/action.yml`](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/publish-nightly/action.yml) (Publish nightly), [`publish-release/action.yml`](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/publish-release/action.yml) (Publish release), [`validate-release/action.yml`](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/validate-release/action.yml) (Validate release)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["Consumer workflow"]
  node_caller["Caller workflow<br/>GitHub Actions workflow"]
  node_plugin_metadata["plugin.yml<br/>plugin metadata"]
  node_release_tag{{"Pushed version tag<br/>Git ref"}}
  node_job_outputs["Promoted job outputs<br/>workflow contract"]
end

subgraph group_actions["Composite actions"]
  node_build_action["Build PHAR<br/>composite action<br/>[action.yml]"]
  node_validate_action["Validate release<br/>composite action<br/>[action.yml]"]
  node_publish_release_action["Publish release<br/>composite action<br/>[action.yml]"]
  node_publish_nightly_action["Publish nightly<br/>composite action<br/>[action.yml]"]
  node_linter["Repository linter<br/>quality workflow<br/>[linter.yml]"]
end

subgraph group_github["GitHub platform"]
  node_artifact_store[("Actions artifacts<br/>artifact storage")]
  node_git_refs{{"Git refs and tags<br/>GitHub refs"}}
  node_github_releases["GitHub Releases<br/>release service"]
end

node_php_binaries["PMMP PHP binaries<br/>PHP runtime provider"]
node_composer["Composer<br/>optional dependency installer"]
node_phar_package["PHAR package<br/>build output"]
node_poggit["Poggit CI<br/>optional staging service"]

node_caller -->|"tag release gate"| node_validate_action
node_release_tag -->|"compare version"| node_validate_action
node_plugin_metadata -->|"declared version"| node_validate_action
node_caller -->|"invoke after checkout"| node_build_action
node_plugin_metadata -->|"read metadata"| node_build_action
node_php_binaries -->|"provision PHP"| node_build_action
node_composer -.->|"when enabled"| node_build_action
node_build_action -->|"package and compress"| node_phar_package
node_build_action -->|"upload PHAR"| node_artifact_store
node_build_action -->|"emit metadata and artifact ID"| node_job_outputs
node_build_action -.->|"optional staging"| node_poggit
node_job_outputs -->|"pass across jobs"| node_publish_release_action
node_artifact_store -->|"download PHAR"| node_publish_release_action
node_publish_release_action -->|"create stable release"| node_github_releases
node_job_outputs -->|"pass across jobs"| node_publish_nightly_action
node_artifact_store -->|"download PHAR"| node_publish_nightly_action
node_caller -->|"checkout required"| node_publish_nightly_action
node_publish_nightly_action -->|"force-update nightly"| node_git_refs
node_publish_nightly_action -->|"upsert prerelease"| node_github_releases

click node_build_action "https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/build-phar/action.yml"
click node_validate_action "https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/validate-release/action.yml"
click node_publish_release_action "https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/publish-release/action.yml"
click node_publish_nightly_action "https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/publish-nightly/action.yml"
click node_linter "https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/.github/workflows/linter.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_caller,node_plugin_metadata,node_release_tag,node_job_outputs toneBlue
class node_build_action,node_validate_action,node_publish_release_action,node_publish_nightly_action,node_linter toneAmber
class node_artifact_store,node_git_refs,node_github_releases toneMint
class node_php_binaries,node_composer,node_phar_package,node_poggit toneNeutral
```

## Components

### Consumer workflow

Caller repository job and cross-job output boundary.

- **Caller workflow**: GitHub Actions workflow · Runs after checkout on a caller-selected runner.
- **plugin.yml**: plugin metadata · Supplies name, version, and PocketMine-MP API metadata.
- **Pushed version tag**: Git ref · Immutable release trigger and validation input.
- **Promoted job outputs**: workflow contract · Carries artifact ID and build metadata across jobs.

### Composite actions

Reusable delivery action entry points.

- [Build PHAR](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/build-phar/action.yml): composite action · Central packaging stage. · `build-phar/action.yml`
- [Validate release](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/validate-release/action.yml): composite action · Fails when normalized tag and declared version differ. · `validate-release/action.yml`
- [Publish release](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/publish-release/action.yml): composite action · Creates a stable GitHub Release from a build artifact. · `publish-release/action.yml`
- [Publish nightly](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/publish-nightly/action.yml): composite action · Moves the nightly tag and creates or updates its prerelease. · `publish-nightly/action.yml`
- [Repository linter](https://github.com/axolotl-pm/pmmp-plugin-actions/blob/main/.github/workflows/linter.yml): quality workflow · `.github/workflows/linter.yml`

### GitHub platform

GitHub Actions storage, refs, and release services.

- **Actions artifacts**: artifact storage · Explicit build-to-publication boundary.
- **Git refs and tags**: GitHub refs · Nightly publication force-updates the mutable nightly tag.
- **GitHub Releases**: release service · Hosts attached stable and nightly PHAR binaries.

### Other components

- **PMMP PHP binaries**: PHP runtime provider
- **Composer**: optional dependency installer · Included when enabled by build inputs.
- **PHAR package**: build output · Compressed plugin binary produced from configured sources and assets.
- **Poggit CI**: optional staging service

## Connections

- Caller workflow → Validate release: tag release gate
- Pushed version tag → Validate release: compare version
- plugin.yml → Validate release: declared version
- Caller workflow → Build PHAR: invoke after checkout
- plugin.yml → Build PHAR: read metadata
- PMMP PHP binaries → Build PHAR: provision PHP
- Composer → Build PHAR: when enabled
- Build PHAR → PHAR package: package and compress
- Build PHAR → Actions artifacts: upload PHAR
- Build PHAR → Promoted job outputs: emit metadata and artifact ID
- Build PHAR → Poggit CI: optional staging
- Promoted job outputs → Publish release: pass across jobs
- Actions artifacts → Publish release: download PHAR
- Publish release → GitHub Releases: create stable release
- Promoted job outputs → Publish nightly: pass across jobs
- Actions artifacts → Publish nightly: download PHAR
- Caller workflow → Publish nightly: checkout required
- Publish nightly → Git refs and tags: force-update nightly
- Publish nightly → GitHub Releases: upsert prerelease