Add Arcane Docker Compose Deploy GitHub Action

[nsheaps]

Summary

This PR introduces a new GitHub Action for deploying Docker Compose stacks to Arcane via GitOps sync. The action automates the discovery and management of compose files, eliminating the need for manual git sync configuration in Arcane.

Key Changes

• New Action: arcane-deploy — A composite GitHub Action that:

  • Auto-discovers Docker Compose files from a directory or explicit file list
  • Creates or updates GitOps syncs in Arcane via REST API
  • Manages git repository registration in Arcane (creates if missing, updates credentials)
  • Supports immediate sync triggering and auto-sync polling configuration
  • Exports shared environment variables for use across stacks

• Implementation Details:

  • action.yml — Defines 13 configurable inputs and 3 outputs
  • action.sh — 344-line bash script with:
    • Compose file discovery (directory scan with pattern matching or explicit list)
    • Intelligent sync naming derived from directory structure
    • API helper for authenticated requests to Arcane
    • Repository and sync upsert logic (create or update, never delete)
    • Environment variable export for workflow sharing
    • Comprehensive logging with GitHub Actions grouping and masking

• Documentation — Updated README with:

  • Feature overview and use case examples
  • Three usage patterns (directory scan, explicit files, with env vars)
  • Complete input/output reference table

Notable Implementation Details

• Compose file discovery supports both docker-compose.y[a]ml and compose.y[a]ml naming conventions
• Sync names are intelligently derived from directory structure (e.g., stacks/myapp/compose.yml → {prefix}-myapp)
• API requests include proper error handling with HTTP status code validation
• Git credentials are updated on each run to keep tokens current
• Supports multiple git authentication types: none, HTTP (token-based), and SSH
• All sensitive values (API key, tokens) are properly masked in logs

https://claude.ai/code/session_01PrmzWtCEcxJTMjxXje3ndd

[nsheaps]

⬇️ Superseded by v4 review — Original v1 review (69/100)

Structured 8-Category Review — Overall Score: 69/100 🚨

This review has been superseded by the v4 review which scores 90/100 with all 8 categories passing.

All findings from this review were addressed in subsequent iterations.

[nsheaps]

⬇️ Superseded by v4 review — Original v2 review (85/100)

Re-Review (v2): Overall Score 85/100 (up from 69)

This review has been superseded by the v4 review which scores 90/100 with all 8 categories passing.

Remaining findings from this review were addressed in v3 and v4.

[nsheaps]

N3 (Medium): jq and curl runtime dependencies undeclared/unguarded

Both are required but no pre-flight check exists. On self-hosted or container runners, a missing jq or curl produces an obscure error deep in execution.

Fix (add near top of script):

for cmd in curl jq; do
  command -v "${cmd}" >/dev/null 2>&1 || {
    log_error "Required dependency '${cmd}' is not installed"
    exit 1
  }
done

Reported in: Pattern Matching

[nsheaps]

⬇️ Superseded by v4 review — Original v3 review (88/100)

Re-Review (v3): Overall Score 88/100 (up from 85)

This review has been superseded by the v4 review which scores 90/100 with all 8 categories passing.

General QA findings (M5, M7, N2) were fixed in v4.

[nsheaps]

M4 (Medium, still present): sync_name_from_path collisions on multi-level directories

The function uses only basename of the parent directory. Two different compose files with matching leaf directory names (e.g., services/backend/api/compose.yml and services/frontend/api/compose.yml) will both produce prefix-api, causing one sync to silently overwrite the other.

Mitigated by the maxdepth 2 scan limit but not eliminated. Non-blocking — track as follow-up.

Reported in: General QA, Simplicity

[nsheaps]

Re-Review (v4): Overall Score 90/100 — ALL 8 CATEGORIES PASS

Category	v1	v2	v3	v4	Status
Best Practices	74	95	96	97	✅
Documentation	81	94	96	96	✅
Security	42	82	90	90	✅
Flexibility	62	82	90	90	✅
General QA	62	76	80	88	✅
Simplicity	72	82	86	87	✅
Pattern Matching	88	84	85	85	✅
Usability	72	83	85	85	✅

✅ ≥85% — Target: 85%+ all categories — TARGET MET

Verdict: All 8 categories at 85%+. Ready to merge.

All 3 General QA fixes verified:

1. M5: Compose file deduplication (action.sh:155-165) — seen array eliminates duplicates, handles empty array safely
2. M7: Omit token on auth-type=none (action.sh:222-235) — conditional payload matches update path pattern
3. N2: Log trigger-sync failures (action.sh:319-324) — if ! with warning replaces silent || true

Journey: 0/8 passing (v1, score 69) → 2/8 (v2, 85) → 7/8 (v3, 88) → 8/8 (v4, 90)

3 medium findings remain (M3 no trap, M4 sync collisions, M14 no tests) — tracked for follow-up, do not block merge.

Full report: .claude/pr-reviews/nsheaps/github-actions/1/1771898462-v4/OVERALL-REPORT.md