Skip to content

Publish your first package

Jump to bottom
Febin Francis edited this page Oct 20, 2026 · 3 revisions

Publish your first HELLO OS package

Can I install HELLO OS from GitHub Packages today? Not yet. The package page is empty, and the repository currently has no workflow that publishes an image. The npm metadata is marked private, so HELLO OS is not configured for npm publishing. The project already has a Dockerfile with separate web and MCP image targets, making GitHub Container Registry (GHCR) the suitable first package format.

Publishing instructions only: no GHCR image was published as part of this documentation change. A GitHub Release provides source archives; it does not create a container image or native installer.

Current package layout

The Dockerfile defines two Compose services: the Next.js web app and MCP sidecar. For an image-based distribution, publish these as two GHCR packages so they can be versioned together:

  • ghcr.io/codesbyfebin/hello-os-web
  • ghcr.io/codesbyfebin/hello-os-mcp

The root Compose configuration currently builds images from source. It is not yet configured to pull published images from GHCR. Publishing the images will not automatically change Compose deployment.

Publish from a local checkout

Use a clean checkout of the exact release tag. Replace 0.2.1 below with the version you publish.

  1. Create a GitHub personal access token with the write:packages scope. Keep it private; do not paste it into this wiki, shell history, or a commit.
  2. Authenticate to GHCR using a local environment variable:
read -rsp "GitHub token: " CR_PAT
printf '\n'
printf '%s' "$CR_PAT" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
unset CR_PAT

Use a Docker credential helper where available. Without one, Docker may save a base64-encoded credential in its local config; log out when you are done if the host is not dedicated to publishing.

  1. Build both image targets from the repository root:
docker build --target web -t ghcr.io/codesbyfebin/hello-os-web:0.2.1 .
docker build --target mcp -t ghcr.io/codesbyfebin/hello-os-mcp:0.2.1 .
  1. Push the versioned images:
docker push ghcr.io/codesbyfebin/hello-os-web:0.2.1
docker push ghcr.io/codesbyfebin/hello-os-mcp:0.2.1
  1. Open the HELLO OS package page, select each package, connect it to this repository, and choose package visibility deliberately. A public source repository does not automatically make every package public.

Recommended automated publishing

The repository does not yet contain a GHCR publishing workflow. Before enabling tag-triggered publishing, add a reviewed GitHub Actions workflow that:

  • runs only after CI succeeds for the tagged commit;
  • sets minimal permissions: contents: read and packages: write;
  • builds both Dockerfile targets and pushes immutable version tags (and optionally a moving latest tag);
  • labels each image with the source repository and release version;
  • supports provenance or SBOM publication only after that build setup is verified.

See GitHub's package publishing with Actions and container image publishing guide. Those docs describe GitHub behavior; they do not mean this repository already has the workflow.

Before announcing a package

  • Confirm the tag matches the intended release and CI passed.
  • Verify each pushed image digest and test pulling versioned tags on a clean host.
  • Confirm the package is linked to this repository and has the intended visibility.
  • Document required environment variables, persistent volumes, ports, and upgrade/backup steps.
  • Do not describe the image as a supported production deployment until security and upgrade behavior are reviewed.

Related HELLO OS pages

Current implementation and audit · API and MCP operations · Roadmap and infrastructure limits

Clone this wiki locally