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

[![Release v1](https://img.shields.io/badge/v1-996677?colorA=151515&style=for-the-badge)](https://git.zyrrus.dev/eighty-six/node-deploy-action/releases) [![Docker](https://img.shields.io/badge/Docker-2496ed?logo=docker&logoColor=white&style=for-the-badge)](https://www.docker.com/) [![Pangolin](https://img.shields.io/badge/Pangolin-151515?style=for-the-badge)](https://docs.fossorial.io/)

Table of Contents

- [About the Project](#about-the-project)
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
    - [Pangolin API token permissions](#pangolin-api-token-permissions)
  - [Installation](#installation)
- [Usage](#usage)
  - [Deploy](#deploy)
  - [Cleanup](#cleanup)
- [Roadmap](#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