{"id":38281481,"url":"https://github.com/glefer/github-runner-manager","last_synced_at":"2026-01-17T01:59:10.334Z","repository":{"id":315409871,"uuid":"1058651018","full_name":"glefer/github-runner-manager","owner":"glefer","description":"Gestion automatisée de runners GitHub auto-hébergés : déploiement, mise à jour, supervision et maintenance simplifiés via une interface CLI et Docker.","archived":false,"fork":false,"pushed_at":"2025-09-26T11:15:48.000Z","size":348,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-26T13:10:57.473Z","etag":null,"topics":["docker","github-actions","github-runner"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glefer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-17T11:19:08.000Z","updated_at":"2025-09-25T06:00:54.000Z","dependencies_parsed_at":"2025-09-18T21:16:12.977Z","dependency_job_id":null,"html_url":"https://github.com/glefer/github-runner-manager","commit_stats":null,"previous_names":["glefer/github-runner-manager"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/glefer/github-runner-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glefer%2Fgithub-runner-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glefer%2Fgithub-runner-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glefer%2Fgithub-runner-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glefer%2Fgithub-runner-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glefer","download_url":"https://codeload.github.com/glefer/github-runner-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glefer%2Fgithub-runner-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T00:50:05.742Z","status":"ssl_error","status_checked_at":"2026-01-17T00:43:11.982Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","github-actions","github-runner"],"created_at":"2026-01-17T01:59:09.698Z","updated_at":"2026-01-17T01:59:10.317Z","avatar_url":"https://github.com/glefer.png","language":"Python","readme":"# GitHub Runner Manager\n\n![Banner](./docs/assets/logo.webp)\n\n[![Workflow State](https://github.com/glefer/github-runner-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/glefer/github-runner-manager/actions/workflows/main.yml)  \n[![codecov](https://codecov.io/gh/glefer/github-runner-manager/branch/main/graph/badge.svg?token=JRjmc0emjT)](https://codecov.io/gh/glefer/github-runner-manager)  \n![Python](https://img.shields.io/badge/python-3.13-blue)  \n[![Docker](https://img.shields.io/docker/pulls/glefer/github-runner-manager)](https://hub.docker.com/r/glefer/github-runner-manager)\n\nA Python application to easily manage your GitHub runners from any server or locally.  \n![Output](./docs/assets/output.webp)\n\n---\n\n## 🚀 Getting Started\n\n### Requirements\n* Python 3.13+\n* Poetry\n\n### Installation\n\n1. Clone:\n```bash\ngit clone https://github.com/glefer/github-runner-manager\ncd github-runner-manager\ncp runners_config.yaml.dist runners_config.yaml\ncp .env.example .env \n# fill the GITHUB_TOKEN with your API token (see: Configuration (.env and runners_config.yaml) section below)\n```\n\n2. Install:\n```bash\npoetry install\n```\n\n3. Help:\n```bash\npoetry run python main.py --help\n```\n\n---\n\n## 📋 Commands\n\n```bash\npython main.py build-runners-images    # Build Docker runner images\npython main.py start-runners           # Start Docker runners\npython main.py stop-runners            # Stop Docker runners\npython main.py remove-runners          # Remove Docker runners\npython main.py check-base-image-update # Check for base image updates\npython main.py list-runners            # List Docker runners\n```\n\n---\n\n## ⏰ Scheduler\n\nThe scheduler automates runner actions (checks, builds, etc.) based on flexible planning defined in `runners_config.yaml`.\n\nIt is automatically started in the container via Supervisor. No manual activation/deactivation is required.\n\nFor more details, see: [docs/scheduler.md](./docs/scheduler.md)\n\n---\n\n## Configuration (.env and runners_config.yaml)\n\nAs of September 2025, GitHub runner management uses a **GitHub personal token** (`admin:org`, `repo` scopes) to dynamically generate a registration token.\n\n\nMinimal `.env` example:\n```dotenv\nGITHUB_TOKEN=ghp_................................\n```\n\n\n**Security:**\n- Never share your personal token\n- Prefer tokens restricted to org/repo scope\n\n---\n\n### Webhooks (notifications)\n\nGitHub Runner Manager supports sending notifications via webhooks to keep you informed of important events like runner start/stop, image builds, or available updates.\n\n![webhook](./docs/assets/webhook.webp)\n\nExample configuration (`runners_config.yaml`):\n```yaml\nwebhooks:\n  enabled: true\n  timeout: 10\n  retry_count: 3\n  retry_delay: 5\n\n  # Slack configuration\n  slack:\n    enabled: true\n    webhook_url: \"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX\"\n    username: \"GitHub Runner Bot\"\n    events:\n      - runner_started\n      - runner_error\n      - build_completed\n      - update_available\n```\n\n**Supported events include:**\n- `runner_started`\n- `runner_stopped`\n- `runner_removed`\n- `runner_error`\n- `runner_skipped`\n- `build_started`\n- `build_completed`\n- `build_failed`\n- `image_updated`\n- `update_available`\n- `update_applied`\n- `update_error`\n\n**Supported providers:**\n- Slack\n- Discord\n- Microsoft Teams\n- Generic webhooks\n\n**Testing webhooks:**\n```bash\n# Test a specific event\npython main.py webhook test --event runner_started --provider slack\n\n# Test all configured events\npython main.py webhook test-all --provider slack\n```\n\n---\n\n## Example Runner Configuration\n\nA sample `runners_config.yaml.dist` file is provided. Copy it to start your own configuration:\n\n```bash\ncp runners_config.yaml.dist runners_config.yaml\n```\n\nExample runner definition:\n```yaml\nrunners:\n  - id: sample\n    name_prefix: my-runner-sample\n    labels: [my-runner-set-sample, sample]\n    nb: 2\n    build_image: ./config/Dockerfile.sample\n    techno: php\n    techno_version: 8.3\n```\n\nSimplified example:\n```yaml\nrunners:\n  - name: runner-1\n    image: ghcr.io/actions/runner:latest\n    labels: [linux, docker]\n```\n\nThe project includes a config schema (`src/services/config_schema.py`) validated with Pydantic.\n\n---\n\n## CLI Commands\n\nThe CLI (powered by Typer) is documented via `--help`:\n\n```bash\npoetry run python main.py --help\n```\n\nCommon commands:\n- `list-runners` – list runners\n- `start-runners` – start runners\n- `stop-runners` – stop runners\n- `remove-runners` – remove runners\n- `check-base-image-update` – check if base images have updates\n\n---\n\n## Usage in Docker Container\n\nA `Dockerfile` is provided for building a custom image.\n\n### Entrypoint\n- `server` → runs the scheduler via Supervisor\n- `\u003cCLI command\u003e` → runs a Python CLI command\n- No argument → prints help/usage\n\n### Example build and run\n```bash\n# Build\ndocker build -t github-runner-manager .\n\n# Run scheduler\ndocker run --rm -it   -v /var/run/docker.sock:/var/run/docker.sock   -v $(pwd)/runners_config.yaml:/app/runners_config.yaml   -v $(pwd)/config:/app/config:ro   github-runner-manager server\n\n# Run CLI (example: list runners)\ndocker run --rm -it   -v /var/run/docker.sock:/var/run/docker.sock   -v $(pwd)/runners_config.yaml:/app/runners_config.yaml   -v $(pwd)/config:/app/config:ro   github-runner-manager list-runners\n```\n\n⚠️ Mounting the Docker socket gives full access to Docker on the host. Use only in trusted environments.\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglefer%2Fgithub-runner-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglefer%2Fgithub-runner-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglefer%2Fgithub-runner-manager/lists"}