انتقل إلى المحتوى

GitHub Management

Guiding Principle

Our GitHub process is built on the principle of automation and "as-code" workflows. We treat issues, documentation, and CI pipelines as versioned artifacts that live alongside our application code.

This document outlines how we manage GitHub issues and continuous integration (CI) workflows in the Labeeb project.

1. Issue Management: Issues as Code

We use GitHub Issues as our single source of truth for project management, but we drive it through a structured, code-first workflow. Instead of manually creating and updating issues in the UI, we define them in version-controlled .jsonl files within the /tasks directory.

Why Manage Issues as Code?

  • Version Control & History: Every change to a task is captured in git, giving us a complete, auditable history.
  • Batch Operations: It allows for powerful, scriptable batch creation and updates, which is far more efficient than manual editing.
  • Consistency: Enforces a consistent structure and format for all tasks.
  • Collaboration: Planning sprints and defining tasks can be done via pull requests, allowing for team review and discussion before the work appears on the board.
  • Single Source of Truth: The entire project—code, infrastructure, and tasks—lives in one place: the git repository.

A suite of scripts located in /scripts/tickets/ is used to synchronize these local files with GitHub.

Issue Management Scripts

This section details the key scripts used to manage the lifecycle of our issues.

tasks_sync.sh - JSONL to GitHub Sync

This is the most important script for our workflow. It provides a powerful, idempotent way to synchronize GitHub issues from local .jsonl files.

Key Features: - Idempotent: Safely run the script multiple times. - Project-Aware: Automatically infers the owner/repo from your git remote. - Smart Labeling: Manages labels within specific namespaces. - Orphan Management: Can automatically close issues on GitHub that no longer exist locally.

Usage: 

bash scripts/tickets/tasks_sync.sh [--repo owner/repo] [--files "tasks/*.jsonl"] [--apply] [--no-close-orphans] [--only-changed]

  • Example: Dry Run --- Preview changes for files modified in your current branch. 
    bash scripts/tickets/tasks_sync.sh --only-changed
  • Example: Apply --- Apply changes for all sprint-related tasks. 
    bash scripts/tickets/tasks_sync.sh --files "tasks/sprint-*.jsonl" --apply

tasks_batch.sh - Advanced Batch Operations

An advanced utility for performing rich, one-off batch actions on existing GitHub issues.

Key Features: - Rich Metadata Updates: Change status, add labels, set assignees, and assign milestones. - Commenting: Add a comment to all targeted issues. - Mark as Duplicate: Close issues as duplicates of another.

Usage: 

bash scripts/tickets/tasks_batch.sh --repo <owner/repo> --ids "<IDs>" ...

  • Example: Set Status --- Set issues to "In Progress" and assign them. 
    bash scripts/tickets/tasks_batch.sh --repo codex-corp/labeeb --ids "API-5, AIB-2" --status "IN PROGRESS" --assignees "hany"
  • Example: Mark Duplicate --- Close an issue as a duplicate and add a comment. 
    bash scripts/tickets/tasks_batch.sh --repo codex-corp/labeeb --ids "API-10" --close --comment "Superseded by #123." --duplicate-of 123

tasks_create.sh - Bulk Create Issues

A simple, one-way script to quickly create multiple GitHub issues from a local .jsonl file. This script is not idempotent.

Usage: 

bash scripts/tickets/tasks_create.sh <owner/repo> [assignee] [jsonl-file]

  • Example: Create and Assign --- Create issues from the default file path and assign them. 
    bash scripts/tickets/tasks_create.sh codex-corp/labeeb "hany"
  • Example: Create Unassigned --- Create issues from a different file without an assignee. 
    bash scripts/tickets/tasks_create.sh codex-corp/labeeb "" "tasks/sprint-2-unassigned.jsonl"

tasks_export.sh - Export Project Items

This script exports all items from a GitHub Project (v2) board into structured data files.

Usage: 

bash scripts/tickets/tasks_export.sh --owner <ORG> (--project <NUM> | --title "<TITLE>")

  • Example: Export by Number --- Export a project by its number. 
    bash scripts/tickets/tasks_export.sh --owner codex-corp --project 2
  • Example: Export by Title --- Export a project by its title to a specific directory. 
    bash scripts/tickets/tasks_export.sh --owner codex-corp --title "@labeeb" --out ./project_exports

2. GitHub Actions & CI Overview

Our CI/CD is built around GitHub Actions. The workflows are defined in YAML files under .github/workflows/.

CI Pipeline Types

  • Service-Specific CI --- Each microservice (api, ai-box, scraper) has its own pipeline that runs linting, type-checking, tests, and Docker builds. Workflows: api-ci.yml, ai-box.yml

  • Smoke Tests --- These tests run against a live, containerized environment to verify critical end-to-end functionality. Workflows: search-smoke-bm25.yml, aibox-retrieve.yml

3. Interacting with CI from the CLI

The gh (GitHub CLI) tool is essential for interacting with our CI pipelines from the command line.

You can list recent runs for a specific workflow to check its status. For example, to see the last run of the BM25 smoke test on the main branch:

gh run list -R codex-corp/labeeb --workflow "search-smoke-bm25.yml" --branch main --limit 1

To view the details of a specific run and see the logs, you can use:

gh run view <RUN_ID>

You can also watch a run in real-time:

gh run watch <RUN_ID>