Metadata-Version: 2.4
Name: cicd-jobs-monitor
Version: 0.4.0
Summary: Generic GitLab CI/CD pipeline and jobs monitor (htop-style TTY)
Author: Hammed Ramdani, SIMOHRA SAS
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/hammedRamdani/cicd-jobs-monitor
Project-URL: Repository, https://gitlab.com/hammedRamdani/cicd-jobs-monitor
Project-URL: Issues, https://gitlab.com/hammedRamdani/cicd-jobs-monitor/-/issues
Keywords: gitlab,cicd,pipeline,monitor,cli
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# cicd-monitor

A terminal dashboard for **GitLab CI/CD** pipelines. It works like `htop`: it
stays open, refreshes in place, and shows the orchestrator pipeline, child
pipelines (bridges), and jobs that ran directly on child projects.

**Package name (pip):** `cicd-jobs-monitor`  
**Command after install:** `cicd-monitor`  
**Needs:** Python 3.10+ (or pipx / Homebrew). No extra runtime libraries.  
**License:** [AGPL-3.0-or-later](LICENSE)

| You want | Read this |
|---|---|
| Install and log in | [docs/INSTALL.md](docs/INSTALL.md) |
| First run and everyday commands | [docs/USAGE.md](docs/USAGE.md) |
| AI agent / automation notes | [AGENTS.md](AGENTS.md) |
| Publish a new version to PyPI | [docs/PYPI.md](docs/PYPI.md) |

## 60-second start

```bash
# 1. Install (once)
pipx install cicd-jobs-monitor

# 2. Auth — pick ONE of these
glab auth login                          # already using glab? nothing else to do
# or
export GITLAB_TOKEN=glpat-…              # GitLab → Preferences → Access Tokens (read_api)

# 3. Run from a GitLab clone, or pass the project
cd your-gitlab-repo
cicd-monitor                             # uses .cicd-monitor.yml if present
cicd-monitor --project group/my-app      # any project, no config file
```

Quit the live dashboard with `Ctrl+C`.

## What you can do

| Goal | Command |
|---|---|
| Watch every active run (default) | `cicd-monitor` |
| One snapshot, then quit | `cicd-monitor --once` |
| Follow one pipeline id | `cicd-monitor --pipeline 42` |
| Self-managed GitLab | `cicd-monitor --host https://gitlab.example --project group/app` |
| Bundled org profile | `cicd-monitor --profile cdd` or `--profile cot-optim` |
| Token in a file (not `KEY=value`) | `cicd-monitor --token-file ~/.config/cicd-monitor/token` |

`--once` exit codes: `0` all good, `1` a run failed, `2` could not talk to GitLab, `130` interrupted.

## Auth (short)

The tool never asks you to paste the GitLab URL of *this* repo to install it.
It only needs a token so it can call the GitLab API.

1. `--token-file` / `GITLAB_TOKEN_FILE` — file contains the **raw token** (or `Bearer …`)
2. `GITLAB_TOKEN` or `GITLAB_OAUTH_TOKEN` in the environment
3. `GITLAB_TOKEN=` in `./.env` or `./.env.local` (walks up to the git root)
4. **glab** login for the host of the current git remote

`glpat-…` tokens are sent as `PRIVATE-TOKEN`. Other tokens (glab OAuth) are
sent as `Authorization: Bearer`. Override with `GITLAB_AUTH=bearer` or `pat`.

Details and why a token *file* is better than a dotenv bag: [docs/INSTALL.md](docs/INSTALL.md).

## Use it in your own repo

Copy [profiles/cdd.example.yml](profiles/cdd.example.yml) or
[profiles/cot-optim.yml](profiles/cot-optim.yml) to `.cicd-monitor.yml` at the
**git root**. Paths are enough; numeric IDs are optional.

```yaml
schema: 1
name: my-app
host: https://gitlab.com
orchestrator:
  path: my-group/my-cicd
children:
  - { path: my-group/backend, label: backend }
presets:
  DEPLOY_DEV: trigger_deploy_dev    # GitLab bridge job name
```

Then, from that repo:

```bash
cicd-monitor
```

## Behaviour

- **Watch** (default): stay open, track active orchestrator runs in parallel
- **Pin** (`--pipeline`, or `--preset` + `--once`): one pipeline
- Follows child pipelines via bridges
- Surfaces direct runs on child projects
- Keeps failed / canceled runs on screen until a newer orchestrator run
- Recovers from Wi-Fi drops and laptop sleep
- Optional desktop notifications on macOS and Linux

## Development

```bash
python3 -m pip install -e '.[dev]'
python3 -m pytest
python3 scripts/build_zipapp.py
```

## Copyright

Copyright (C) 2026 Hammed Ramdani / SIMOHRA SAS

This program is free software under AGPL-3.0-or-later. If you run a
modified version as a network service, you must offer the corresponding
source to its users.
