{"id":48435540,"url":"https://github.com/imbus/testbench-ecosystem-documentation","last_synced_at":"2026-04-06T12:31:06.260Z","repository":{"id":346676329,"uuid":"1159978666","full_name":"imbus/testbench-ecosystem-documentation","owner":"imbus","description":"This repo hosts the documentation of several TestBench Ecosystem projects","archived":false,"fork":false,"pushed_at":"2026-03-25T00:35:42.000Z","size":2630,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-26T04:54:47.461Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/imbus.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":"2026-02-17T11:54:27.000Z","updated_at":"2026-03-25T00:35:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imbus/testbench-ecosystem-documentation","commit_stats":null,"previous_names":["imbus/testbench-ecosystem-documentation"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/imbus/testbench-ecosystem-documentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbus%2Ftestbench-ecosystem-documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbus%2Ftestbench-ecosystem-documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbus%2Ftestbench-ecosystem-documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbus%2Ftestbench-ecosystem-documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imbus","download_url":"https://codeload.github.com/imbus/testbench-ecosystem-documentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbus%2Ftestbench-ecosystem-documentation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31473271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: 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":[],"created_at":"2026-04-06T12:31:06.195Z","updated_at":"2026-04-06T12:31:06.254Z","avatar_url":"https://github.com/imbus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TestBench Ecosystem Documentation\n\nMulti-instance Docusaurus 3 documentation portal for the TestBench Ecosystem by imbus AG. Each tool has its own documentation set with independent versioning.\n\n## Repository layout\n\n```\nimbus/                                          # GitHub org / parent folder\n├── testbench-ecosystem-documentation/          # This repo (Docusaurus site)\n│   ├── .github/workflows/\n│   │   ├── release-pages.yml                   # Deploy to GitHub Pages on push to main\n│   │   ├── pr-preview-surge.yml                # Deploy PR previews to Surge.sh\n│   │   └── version-tool-docs.yml               # Create versioned docs from tool releases\n│   └── docusaurus/\n│       ├── docs/                               # Global ecosystem docs (route: /docs/)\n│       ├── \u003ctool-id\u003e/                          # Tool \"next\" docs (git-ignored, synced for dev)\n│       ├── \u003ctool-id\u003e_versions.json             # Released versions (committed)\n│       ├── \u003ctool-id\u003e_versioned_docs/           # Versioned doc snapshots (committed)\n│       ├── \u003ctool-id\u003e_versioned_sidebars/       # Versioned sidebars (committed)\n│       ├── sidebars_\u003ctool-id\u003e.ts               # Tool sidebar definition\n│       ├── tools.config.json                   # Tool metadata (label, description, logo)\n│       ├── scripts/\n│       │   ├── sync-docs.mjs                   # Copies docs from neighbor repos\n│       │   └── add-tool.mjs                    # Interactive wizard for adding tools\n│       ├── docusaurus.config.ts                # Main site config (auto-discovers tools)\n│       └── package.json\n├── testbench-cli-reporter/                     # Tool repo (neighbor)\n│   └── docs/                                   # Documentation source\n├── testbench-requirement-service/              # Tool repo (neighbor)\n│   └── docs/                                   # Documentation source\n└── ...                                         # More tool repos\n```\n\n**Important**: Tool repositories must be cloned as siblings of this repo (same parent directory). The folder name of each tool repo must match its `tool-id` in `tools.config.json`.\n\n## Local development\n\nAll commands run from the `docusaurus/` directory:\n\n```bash\ncd docusaurus\nnpm install\n```\n\n### Start the dev server\n\n```bash\nnpm run dev\n```\n\nThis runs two things concurrently:\n\n1. **sync:watch** — copies the `docs/` folder from each neighboring tool repo into `docusaurus/\u003ctool-id\u003e/` and watches for changes.\n2. **docusaurus start** — launches the dev server at `http://localhost:3000` with hot reload.\n\nWhen you edit files in a tool's `docs/` folder, changes are automatically synced and the browser reloads.\n\n### Sync specific tools only\n\n```bash\n# Via argument\nnpm run dev -- --repos testbench-cli-reporter\n\n# Via environment variable\nSYNC_REPOS=testbench-cli-reporter npm run dev\n```\n\n### Other commands\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Production build (only versioned/released tools) |\n| `npm run start` | Dev server without doc syncing |\n| `npm run serve` | Serve a production build locally |\n| `npm run sync` | One-time sync from neighbor repos |\n| `npm run typecheck` | TypeScript type checking |\n| `npm run clear` | Clear Docusaurus cache |\n| `npm run add-tool` | Interactive wizard to register a new tool |\n\n### Environment variables\n\n| Variable | Description |\n|----------|-------------|\n| `INCLUDE_NEXT=true` | Include unreleased (\"next\") docs in production builds |\n| `SYNC_REPOS=tool1,tool2` | Comma-separated list of tools to sync |\n\n## Adding a new tool\n\n### 1. Register the tool in this repo\n\nRun the interactive wizard:\n\n```bash\ncd docusaurus\nnpm run add-tool\n```\n\nThis creates:\n- An entry in `tools.config.json`\n- A sidebar file `sidebars_\u003ctool-id\u003e.ts`\n- A starter doc at `\u003ctool-id\u003e/intro.md`\n\nThe tool auto-discovers from the sidebar file and appears in the Ecosystem navbar dropdown.\n\nAlternatively, do it manually:\n\n1. Add the tool to `docusaurus/tools.config.json`:\n   ```json\n   {\n     \"my-new-tool\": {\n       \"label\": \"My New Tool\",\n       \"description\": \"What the tool does.\",\n       \"logo\": \"img/my-new-tool.svg\"\n     }\n   }\n   ```\n2. Create `docusaurus/sidebars_my-new-tool.ts`:\n   ```typescript\n   const sidebars = {\n     myNewToolSidebar: [{ type: 'autogenerated', dirName: '.' }],\n   };\n   export default sidebars;\n   ```\n3. Create `docusaurus/my-new-tool/intro.md` with at least a title.\n\n### 2. Set up the tool repository\n\nThe tool repo must:\n- Be in the same GitHub organization (`imbus`).\n- Have a `docs/` folder at its root with Docusaurus-compatible markdown.\n- Be named exactly like the `tool-id` used in this repo.\n\n### 3. Add the release trigger workflow\n\nCopy the file `.github/workflows/trigger-docs-release.yml` from an existing tool (e.g., `testbench-cli-reporter`) into the new tool's `.github/workflows/` directory. **No changes are needed** — the workflow reads the tool-id from the repository name and the version from the release tag automatically.\n\n### 4. Ensure the `ECOSYSTEM_DOCS_TOKEN` secret is available\n\nThe tool repo needs a secret called `ECOSYSTEM_DOCS_TOKEN` — a GitHub PAT (or fine-grained token) with permission to trigger `repository_dispatch` on `testbench-ecosystem-documentation`. This is best configured as an organization-level secret shared across all tool repos.\n\n## Versioning\n\nEach tool has independent versioning. Versioned files are committed to this repo; the \"next\" (current/unreleased) docs are git-ignored and synced from the tool repo during development.\n\n### Automated versioning (recommended)\n\nWhen you create a **GitHub release** in a tool repository:\n\n1. The tool's `trigger-docs-release.yml` workflow fires.\n2. It sends a `repository_dispatch` event to this repo with the tool-id and version.\n3. This repo's `version-tool-docs.yml` workflow:\n   - Downloads the `docs/` folder from the release tag.\n   - Runs `docusaurus docs:version:\u003ctool-id\u003e \u003cversion\u003e` to create a versioned snapshot.\n   - Commits the versioned docs to a new branch and opens a PR.\n4. The PR triggers a Surge.sh preview deployment for review.\n5. Merging the PR triggers a GitHub Pages production deployment.\n\n```\n┌──────────────┐    repository_dispatch    ┌──────────────────────────┐\n│  Tool repo   │ ────────────────────────► │  ecosystem-docs repo     │\n│  (release)   │  tool_id, version, tag    │  version-tool-docs.yml   │\n└──────────────┘                           └────────────┬─────────────┘\n                                                        │\n                                                        ▼\n                                              Create branch + PR\n                                                        │\n                                                        ▼\n                                              PR preview (Surge.sh)\n                                                        │\n                                                        ▼\n                                              Merge → GitHub Pages\n```\n\n### Manual versioning\n\nFrom the `docusaurus/` directory:\n\n```bash\nnpm run docusaurus -- docs:version:\u003ctool-id\u003e \u003cversion\u003e\n```\n\nExample:\n\n```bash\nnpm run docusaurus -- docs:version:testbench-cli-reporter 1.3.0\n```\n\nThis snapshots the current docs from `docusaurus/\u003ctool-id\u003e/` into versioned directories.\n\n### Version files\n\n| Path | Content |\n|------|---------|\n| `\u003ctool-id\u003e_versions.json` | Array of released version numbers |\n| `\u003ctool-id\u003e_versioned_docs/version-X.Y.Z/` | Frozen docs for that version |\n| `\u003ctool-id\u003e_versioned_sidebars/version-X.Y.Z-sidebars.json` | Frozen sidebar for that version |\n\n## CI/CD\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `release-pages.yml` | Push to `main` | Build and deploy to GitHub Pages |\n| `pr-preview-surge.yml` | Pull request events | Deploy preview to `\u003crepo\u003e-pr-\u003cnumber\u003e.surge.sh` |\n| `version-tool-docs.yml` | `repository_dispatch` from tool repos | Create versioned docs PR |\n\n### Required secrets\n\n| Secret | Scope | Used by |\n|--------|-------|---------|\n| `SURGE_TOKEN` | This repo | PR preview deployments |\n| `ECOSYSTEM_DOCS_TOKEN` | Org-level (all repos) | Tool repos: trigger `repository_dispatch`. This repo: checkout private tool repos for docs download. |\n\nThe `ECOSYSTEM_DOCS_TOKEN` should be a fine-grained PAT (or classic PAT) with:\n- **Read access** to contents of all tool repositories in the org\n- **Write access** to trigger `repository_dispatch` on this repo\n\nConfiguring it as an **organization-level secret** shared across all repos is the simplest approach.\n\n## Troubleshooting\n\n- **Tool doesn't appear in the Ecosystem dropdown**: Ensure `sidebars_\u003ctool-id\u003e.ts` exists and `docusaurus/\u003ctool-id\u003e/intro.md` exists.\n- **`npm run dev` doesn't sync a tool**: The tool repo must be cloned as a sibling directory with a name matching the tool-id. Check `tools.config.json`.\n- **Versioned tool doesn't show in production build**: Only tools with at least one entry in `\u003ctool-id\u003e_versions.json` are included in production builds.\n- **Automated versioning PR not created**: Check that `ECOSYSTEM_DOCS_TOKEN` is set in the tool repo and has `repo` scope on this repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimbus%2Ftestbench-ecosystem-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimbus%2Ftestbench-ecosystem-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimbus%2Ftestbench-ecosystem-documentation/lists"}