n8n-nodes-gh-project-promoter

Description

n8n-nodes-gh-project-promoter is an n8n community node that runs ghpp (GitHub Project Promoter) from within n8n workflows.

ghpp automates status transitions in GitHub Projects V2 by promoting items through a defined flow:

full   : inbox -> plan -> ready -> doing
simple : inbox -> doing

Workflow modes

In simple mode, Promote Plan Enabled and Promote Ready Enabled are silently ignored, and stale doing items are demoted back to inbox instead of ready.

Full-mode phase constraints

The inbox -> plan transition is enabled by default. Disable it with Promote Plan Enabled = false when you want to manage Plan entries manually.

The plan -> ready transition is opt-in (disabled by default). Enable it with Promote Ready Enabled and attach the configured Planned Label to items that are ready to move on.

Installation

Via n8n Community Nodes (recommended)

1. Open Settings > Community Nodes in your n8n instance.
2. Search for n8n-nodes-gh-project-promoter.
3. Click Install.

Manual installation

cd ~/.n8n/custom
npm install n8n-nodes-gh-project-promoter

The postinstall script automatically downloads the appropriate ghpp binary from GitHub Releases. No additional setup is needed.

Prerequisites

• n8n self-hosted instance (Docker recommended)
• GitHub Personal Access Token with the following scopes:
  • repo
  • project
• Supported platforms:
  • linux/amd64
  • linux/arm64
  • darwin/arm64

Credentials

1. In n8n, go to Credentials > New Credential.
2. Search for GHPP API.
3. Enter your GitHub Personal Access Token in the Token field.

The credential is automatically verified against the GitHub API (GET /user) upon saving.

Required token scopes

Node Parameters

Required

Optional

Status Settings (collection)

Override the default status names to match your project board configuration.

Output

The node outputs the JSON result of ghpp promote. Structure:

{
	"summary": { "promoted": 4, "skipped": 2, "total": 6 },
	"phases": {
		"plan": {
			"summary": { "promoted": 3, "skipped": 1, "total": 4 },
			"results": [
				{
					"item": {
						"id": "PVTI_xxx",
						"title": "Issue title",
						"url": "https://github.com/owner/repo/issues/1",
						"status": "Backlog"
					},
					"action": "promoted",
					"to_status": "Plan"
				}
			]
		},
		"ready": {
			"summary": { "promoted": 0, "skipped": 0, "total": 0 },
			"results": []
		},
		"doing": {
			"summary": { "promoted": 1, "skipped": 1, "total": 2 },
			"results": [
				{
					"item": {
						"id": "PVTI_yyy",
						"title": "Another issue",
						"url": "https://github.com/owner/repo/issues/2",
						"status": "Ready"
					},
					"action": "skipped",
					"reason": "repository already has doing issue"
				}
			]
		}
	}
}

Guarantees:

• phases.plan, phases.ready, and phases.doing are always present (even when empty).
• phases.plan results are empty when Promote Plan Enabled is off.
• phases.ready results are empty unless Promote Ready Enabled is on.
• results is [] when there are no items (never null).
• action is either "promoted" or "skipped".
• "promoted" includes to_status; "skipped" includes reason.

If the output cannot be parsed as JSON, the node falls back to { "raw": "<stdout>" }.

Example Workflow

A typical setup uses a Cron trigger to run ghpp on a schedule:

[Schedule Trigger] -> [GHPP] -> [Slack / Email / etc.]

1. Schedule Trigger -- fires at your preferred interval (e.g., every hour).
2. GHPP -- runs ghpp promote with your project settings.
3. Notification -- sends the promotion summary to Slack, email, or any other service.

Compatibility

Tested platforms:

• linux/amd64
• linux/arm64
• darwin/arm64

License

MIT

The ghpp binary is distributed under its own license. See douhashi/ghpp for details.

Resources

• ghpp repository -- the underlying CLI tool
• n8n-nodes-gh-project-promoter repository -- this package
• n8n Community Nodes documentation