node-deploy-action/README.md

Composite Gitea/GitHub Actions for building, deploying, and cleaning up Node.js containers behind Pangolin

Table of Contents

• About the Project
• Getting Started
  • Prerequisites
    • Pangolin API token permissions
  • Installation
• Usage
  • Deploy
  • Slug
  • Cleanup
• Roadmap

About the Project

This repo bundles a small set of composite actions that handle the full lifecycle of a containerized Node.js app: building the Docker image, deploying it to a self-hosted runner, and registering (or tearing down) the corresponding Pangolin resource. The goal is a minimal, opinionated drop-in for production and preview-branch deployments without pulling in a heavy CI platform.

Getting Started

Follow these steps to wire the actions into a repository.

Prerequisites

You'll need a self-hosted runner with Docker installed and network access to a Pangolin instance. The following secrets must be available to the workflow.

Secret

PANGOLIN_API_URL

PANGOLIN_API_KEY

PANGOLIN_ORG_ID

PANGOLIN_DOMAIN_ID

PANGOLIN_SITE_ID

PANGOLIN_TARGET_IP

A dockerfile at the repo root is expected by the deploy action. See examples/docker/ for Next.js and Astro templates.

Pangolin API token permissions

The PANGOLIN_API_KEY must be scoped to the following actions (API v1):

• GET /org/{id}/resources
• PUT /org/{id}/resource
• POST /resource/{id}
• DELETE /resource/{id}
• GET /resource/{id}/targets
• PUT /resource/{id}/target
• DELETE /target/{id}

Installation

No installation is needed — reference the actions directly from a workflow.

- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/deploy@v1

---

Usage

⚠️ Warning: This action is tailored to a specific self-hosted runner + Pangolin setup. Adapt the scripts before reusing elsewhere.

See examples/deploy.yml for a complete workflow covering production, preview, and cleanup.

Deploy

Builds the Docker image, starts the container, and registers a Pangolin resource.

- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/deploy@v1
  with:
    app-name: my-app
    tag: production
    port: "3001"
    environment: production
    subdomain: my-app

Inputs

app-name

Application name (used for image/container naming)

tag

Image/container tag (e.g. production or a branch slug)

port

Host port to expose

internal-port

Port the app listens on inside the container (default 3000)

environment

production or preview

subdomain

Subdomain for the Pangolin resource

build-args

Extra KEY=VALUE docker build args (space-separated)

Slug

Derives a URL-safe slug and a deterministic port from a branch name. Strips refs/heads/ so either github.ref_name or github.event.ref works.

- id: slug
  uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/slug@v1
  with:
    branch: ${{ github.ref_name }}

Outputs: slug, port.

Cleanup

Stops the preview container and removes its Pangolin resource. Intended for delete branch events.

- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/cleanup@v1
  with:
    app-name: my-app
    slug: ${{ steps.slug.outputs.slug }}

Roadmap

• Core actions
  • Build + deploy container
  • Register Pangolin resource
  • Preview slug + deterministic port
  • Cleanup on branch delete
• Dockerfile templates
  • Next.js
  • Astro
  • Remix / SvelteKit
• Quality of life
  • Configurable Docker build context
  • Health-check gating before Pangolin registration
  • Multi-arch image builds