Skip to content

README.md

Latest commit

 

History

History
141 lines (102 loc) · 5.98 KB

README.md

File metadata and controls

141 lines (102 loc) · 5.98 KB

github2stackfield

github2stackfield is an x0 web application that bridges GitHub Issues with Stackfield Tasks.
It lets you search GitHub issues, inspect their details, and create corresponding Stackfield tasks — all from a clean, Bootstrap-styled browser frontend.

Architecture

Layer Technology
Browser frontend x0 JavaScript framework with Bootstrap default theme
Backend services Python WSGI scripts via python-micro-esb
Database PostgreSQL (shared x0 instance)
Deployment Apache2 + mod_wsgi (Docker or bare-metal)

Screens

Screen 1 — User Credentials

Configure and verify API access for both platforms.

  • GitHub API Credentials — enter your GitHub username and Personal Access Token.
    Click Verify GitHub Credentials to validate and store them.
  • Stackfield API Credentials — enter your Stackfield e-mail and API token.
    Click Verify Stackfield Credentials to validate and store them.

Screen 2 — Issue / Task Mapping

Search GitHub issues and select one to map to Stackfield.

  1. Enter the target repository (owner/repository) and an optional search term.
  2. Click Search Issues — results populate the issue list below.
  3. Right-click any row and select Connect Stackfield Task to navigate to Screen 3.

Screen 3 — Connect Stackfield Task

Review the selected GitHub issue and create a Stackfield task.

  • GitHub Issue Properties — read-only fields: issue number, state, title, URL.
  • Stackfield Task Mapping — editable fields pre-populated from the issue:
    • Stackfield Room ID — the target Stackfield room / channel identifier.
    • Task Title — editable, defaults to the GitHub issue title.
    • Description — editable, defaults to the GitHub issue body.
    • Priority — Low / Medium / High / Urgent.
  • Click Create New Stackfield Task — a new task is created in Stackfield via the REST API.

Prerequisites

Requirement Notes
Docker Engine With Compose V2 (docker compose)
GitHub Personal Access Token Needs repo scope for private repos, public_repo for public
Stackfield API token See Stackfield workspace settings → Integrations → API

Docker (quick start)

The application uses the official x0 container images:

  • ghcr.io/webcodex1/x0-app — Apache2 + mod_wsgi web application server with the x0 JavaScript framework pre-installed (packages page)
  • ghcr.io/webcodex1/x0-db — PostgreSQL 16 database with the x0 schema pre-installed (packages page)

Both custom images are built automatically on docker compose up --build:

  • docker/Dockerfile extends ghcr.io/webcodex1/x0-app and copies all static files, Python WSGI scripts, and the Apache2 config snippet into the image.
  • docker/Dockerfile.db extends ghcr.io/webcodex1/x0-db and runs the github2stackfield SQL init scripts (database/0*.sql) against the x0 database on first start.
cd docker
docker compose up --build

Then open http://localhost:8080/?appid=github2sf.

No further manual configuration is required.

Project structure

github2stackfield/
├── static/
│   ├── menu.json         # x0 navigation menu definition
│   ├── object.json       # x0 UI objects (formfields, lists, buttons …)
│   └── skeleton.json     # x0 screen layout
├── python/
│   ├── service_implementation.py   # GitHubService + StackfieldService ClassHandlers
│   ├── user_routing.py             # python-micro-esb ServiceRouter routing functions
│   ├── VerifyGitHubCredentials.py  # WSGI – verify GitHub credentials
│   ├── VerifyStackfieldCredentials.py  # WSGI – verify Stackfield credentials
│   ├── SearchGitHubIssues.py       # WSGI – search issues, populate list
│   ├── GetGitHubIssueDetails.py    # WSGI – fetch issue details for Screen 3
│   ├── CreateStackfieldTask.py     # WSGI – create Stackfield task
│   ├── POSTData.py                 # x0 POST body reader helper
│   └── StdoutLogger.py            # logging helper
├── database/
│   ├── 01-create-schema.sql   # github2sf schema + tables
│   ├── 02-insert-config.sql   # x0 app configuration rows
│   └── 03-insert-text.sql     # UI text / i18n entries
├── docker/
│   ├── Dockerfile          # extends x0-app, bakes in static/ python/ apache2.conf
│   ├── Dockerfile.db       # extends x0-db, auto-inits github2sf schema on startup
│   ├── docker-compose.yml
│   ├── db-init.sh          # startup script used by Dockerfile.db
│   └── apache2.conf
└── README.md

python-micro-esb integration

The backend services are built on the python-micro-esb framework:

  • service_implementation.py — contains GitHubService and StackfieldService, both subclassing microesb.ClassHandler. Each class exposes service methods (verify, search_issues, get_issue_details, create_task).
  • user_routing.py — routing functions consumed by ServiceRouter.send(). Each function instantiates the appropriate service class, calls the relevant method, and returns the result.
  • WSGI scripts — thin wrappers that read the x0 POST payload, call ServiceRouter.send(), and return JSON to the x0 frontend.

Stackfield API notes

Stackfield's REST API is available at https://www.stackfield.com/api/v1/.
Key endpoints used:

Endpoint Purpose
GET /v1/user Verify credentials
POST /v1/rooms/{room_id}/tasks Create a new task

The Room ID can be found in Stackfield under Room settings → General → Room ID or via the URL slug.

License

See LICENSE.