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
  • 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. The branch name drives everything else: pushes to the repo's default branch deploy as production, all other branches deploy as previews with a slugified tag, a deterministic host port, and a ${slug}.${app-name} subdomain.

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

Inputs

app-name

Application name (used for image/container naming, and as the production subdomain)

branch

Branch name. Matches against github.event.repository.default_branch to decide production vs. preview. refs/heads/ prefix is stripped.

internal-port

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

build-args

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

env-vars

Runtime env vars for the container, one KEY=VALUE per line. Merged on top of /opt/apps/${app-name}/.env.${environment} on the runner — keys defined here win. Reference secrets here so values stay masked in logs.

env-vars: |
  DATABASE_URL=${{ secrets.DATABASE_URL }}
  API_KEY=${{ secrets.API_KEY }}

Cleanup

Stops the preview container and removes its Pangolin resource. Intended for delete branch events — the slug is derived from the branch name internally.

- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/cleanup@v1
  with:
    app-name: my-app
    branch: ${{ github.event.ref }}

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