feat: enable private GitHub/GitLab repository templates (#1157)

[Kartikayy007]

Description

This PR adds support for using AsyncAPI templates from private GitHub and GitLab repositories, resolving a long-standing feature request.

Changes

• Added isGitSpecifier() helper to detect git-based template URLs
• Modified installTemplate() to skip cache lookup for git specs and delegate authentication to system git configuration
• Added comprehensive test coverage (9 new tests for git URL detection)
• Updated documentation with examples for private git repository usage

How it works

The implementation leverages npm's Arborist (already used for template installation), which natively supports git URLs. Authentication is handled by the system's existing git configuration (SSH keys, HTTPS tokens, .netrc).

Supported formats:

• git+ssh://[email protected]/org/repo.git
• git+https://github.com/org/repo.git
• [email protected]:org/repo.git
• github:org/repo
• gitlab:org/repo

Usage

CLI:

asyncapi generate fromTemplate asyncapi.yaml \
  git+ssh://[email protected]/org/private-template.git \
  -o output

Library:

const generator = new Generator(
  'git+ssh://[email protected]/org/private-template.git',
  'output'
);

Demo

https://github.com/user-attachments/assets/3ba6bb1e-7799-464d-876d-1510777e84fe

Testing

• All tests passing:

• 120 unit tests (including 9 new tests for git URL detection)
• 10 integration tests
• Total: 130/130 passing

• Manual verification:

• Tested with actual private GitHub repository
• Verified multiple git URL formats work correctly
• Confirmed authentication delegates to system git config

Related issue(s)

Resolves #1157

Summary by CodeRabbit

• New Features

  • Install templates directly from Git specifiers (including private repos) with proper git-auth handling and clearer git-source logging.

• Documentation

  • Added a comprehensive guide for using templates from private Git repositories with CLI examples and authentication guidance.

• Tests

  • Added tests covering Git specifier detection and installation flows.

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: de9609bf925e39651cd7f4d5d813ca5addbbf2c8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai[bot]]

Walkthrough

Adds support for templates sourced from Git specifiers by detecting git-style template identifiers, bypassing local cache for git templates, adding tests and mocks, and documenting usage for private Git repositories.

Changes

Cohort / File(s)	Summary
Documentation apps/generator/docs/using-private-template.md	New doc describing using templates from private Git repositories, CLI examples with various git specifiers, authentication guidance, and a library usage example.
Git specifier utility apps/generator/lib/utils.js, apps/generator/lib/__mocks__/utils.js	Adds isGitSpecifier(str) in production and mock; mock exposes __isGitSpecifierValue override. Detects git+ssh/git+https/ssh/git@host:path and github:/gitlab:/bitbucket: npm-style specifiers.
Generator logic apps/generator/lib/generator.js	Detects git templates in installTemplate, skips local cache lookup for git specifiers, and emits debug logging when installing from git sources.
Test mocks apps/generator/test/__mocks__/requireg.js	Adds mock requireg.resolve() returning 'npm/index.js' to satisfy test expectations.
Tests apps/generator/test/generator.test.js, apps/generator/test/utils.test.js	Adds test for installing from a git specifier and comprehensive tests for isGitSpecifier covering positive and negative git formats.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Pay attention to regex/validation correctness in isGitSpecifier (edge cases, refs like #branch/#tag).
• Verify the cache-bypass condition in installTemplate (!force && !isGitTemplate) is correctly updated to !isGitTemplate behavior.
• Confirm tests and mocks (especially requireg mock and mock override flag) align with test runner expectations.

Possibly related PRs

• #1329 — Modifies installTemplate (error messages/logging) in the same function; review for logging or behavior overlap/conflicts.

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main feature: enabling private GitHub/GitLab repository templates for the AsyncAPI generator.
Linked Issues check	✅ Passed	The PR successfully implements the core requirement from issue #1157: adding support for private GitHub/GitLab repository templates. New isGitSpecifier() utility detects git URLs, installTemplate() skips cache for git specs, and tests confirm functionality.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #1157: documentation for private git templates, git specifier detection utility, modified installation logic, test cases, and mock modules for testing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[asyncapi-bot]

What reviewer looks at during PR review

The following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.

1. PR Title: Use a concise title that follows our Conventional Commits guidelines and clearly summarizes the change using imperative mood (it means spoken or written as if giving a command or instruction, like "add new helper for listing operations")

   Note - In Generator, prepend feat: or fix: in PR title only when PATCH/MINOR release must be triggered.

2. PR Description: Clearly explain the issue being solved, summarize the changes made, and mention the related issue.

   Note - In Generator, we use Maintainers Work board to track progress. Ensure the PR Description includes Resolves #<issue-number> or Fixes #<issue-number> this will automatically close the linked issue when the PR is merged and helps automate the maintainers workflow.

3. Documentation: Update the relevant Generator documentation to accurately reflect the changes introduced in the PR, ensuring users and contributors have up-to-date guidance.

4. Comments and JSDoc: Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions, so others can easily understand and use the code.

5. DRY Code: Ensure the code follows the Don't Repeat Yourself principle. Look out for duplicate logic that can be reused.

6. Test Coverage: Ensure the new code is well-tested with meaningful test cases that pass consistently and cover all relevant edge cases.

7. Commit History: Contributors should avoid force-pushing as much as possible. It makes it harder to track incremental changes and review the latest updates.

8. Template Design Principles Alignment: While reviewing template-related changes in the packages/ directory, ensure they align with the Assumptions and Principles. If any principle feels outdated or no longer applicable, start a discussion these principles are meant to evolve with the project.

9. Reduce Scope When Needed: If an issue or PR feels too large or complex, consider splitting it and creating follow-up issues. Smaller, focused PRs are easier to review and merge.

10. Bot Comments: As reviewers, check that contributors have appropriately addressed comments or suggestions made by automated bots. If there are bot comments the reviewer disagrees with, react to them or mark them as resolved, so the review history remains clear and accurate.

[asyncapi-bot]

🚀 Docs preview deployed Below link points directly to the generator docs preview. May the force be with you! → https://691dbf3bea74840c154b8324--asyncapi-website.netlify.app/docs/tools/generator

[sonarqubecloud[bot]]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Kartikayy007]

adding it to draft as unplanned