ngrokgitconfig

README

ngrok-gitconfig

Generate a gitconfig snippet that rewrites each target source domain to the active ngrok tunnel URL.

---

CHINESE README

中文说明

Main Features

🚀 Single-Purpose Command: Fetch active ngrok tunnel URLs and write them as a gitconfig snippet 🔗 Plug-In Design: Output snippet plugs into ~/.gitconfig via git's [include] mechanism 🔄 Symlink-Based Switching: Toggle between LAN and ngrok paths via a single ln -sf 🔐 Multi-Account Support: Pick from a list of ngrok api keys via the -n index flag

Installation

go install github.com/yylego/ngrok-gitconfig/cmd/ngrok-gitconfig@latest

Usage

# Fetch active ngrok tunnels and write the snippet (default api key index 0)
ngrok-gitconfig -c ~/configs/ngrok-gitconfig.yaml -o ~/.gitconfig.gitlab.ngrok

# Pick api key index 1
ngrok-gitconfig -c ~/configs/ngrok-gitconfig.yaml -o ~/.gitconfig.gitlab.ngrok -n 1

Flags

Flag	Default	Note
--config / -c	(required)	path to YAML config
--output / -o	(required)	output path of the gitconfig snippet
--choose / -n	0	api key index

Configuration

YAML config — ~/configs/ngrok-gitconfig.yaml

api_keys:
  - "<ngrok api key 1>" # account 1
  - "<ngrok api key 2>" # account 2 (extras OK, pick via -n flag)
targets:
  - "https://gitlab.example.com/"
  - "http://gitlab.example.com/"

targets are paired by index with the tunnel URLs returned by the ngrok API.

Wire up ~/.gitconfig with [include]

Add at the top of ~/.gitconfig:

[include]
	path = ~/.gitconfig.gitlab.active

LAN snippet — ~/.gitconfig.gitlab.local

Hand-written, does not change:

[url "http://192.168.1.100:8080/"]
	insteadof = https://gitlab.example.com/
[url "http://192.168.1.100:8080/"]
	insteadof = http://gitlab.example.com/

ngrok snippet — ~/.gitconfig.gitlab.ngrok

Touch the snippet file (this command overwrites it on each run):

touch ~/.gitconfig.gitlab.ngrok

Setup symlink

Point active at one of the snippets to start (LAN here):

ln -sf ~/.gitconfig.gitlab.local ~/.gitconfig.gitlab.active

Recommended Aliases

In ~/.zshrc (or ~/.bashrc):

gitlab-use-ngrok() {
    ngrok-gitconfig -c ~/configs/ngrok-gitconfig.yaml -o ~/.gitconfig.gitlab.ngrok "$@" \
        && ln -sf ~/.gitconfig.gitlab.ngrok ~/.gitconfig.gitlab.active
}
alias gitlab-use-local='ln -sf ~/.gitconfig.gitlab.local ~/.gitconfig.gitlab.active'
alias gitlab-use-which='ls -la ~/.gitconfig.gitlab.active'

Usage Examples

# In office (LAN direct)
gitlab-use-local

# Off-LAN (refresh ngrok URLs from API, switch active to ngrok)
gitlab-use-ngrok

# Same as above, pick api key index 1
gitlab-use-ngrok -n 1

# Check which path is now active
gitlab-use-which

📄 License

MIT License - see LICENSE.

---

💬 Contact & Feedback

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Mistake reports? Open an issue on GitHub with reproduction steps
• 💡 Fresh ideas? Create an issue to discuss
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars

Documentation

Overview

Package ngrokgitconfig renders ngrok tunnel URLs as a gitconfig snippet Plug the snippet into ~/.gitconfig via git's [include] mechanism or a symlink

ngrokgitconfig 把 ngrok 隧道 URL 渲染成 gitconfig 片段 通过 git 的 [include] 机制（或符号链接）接入 ~/.gitconfig

Index

• func Generate(ctx context.Context, cfg *Config, keyIdx int) ([]byte, error)
• type Config
  • func LoadConfig(path string) (*Config, error)

Functions

func Generate

func Generate(ctx context.Context, cfg *Config, keyIdx int) ([]byte, error)

Generate fetches the active ngrok tunnel URLs and returns the gitconfig snippet bytes keyIdx must be in [0, len(cfg.APIKeys))

Generate 拉取活跃 ngrok 隧道 URL 并返回 gitconfig 片段字节 keyIdx 范围 [0, len(cfg.APIKeys))

Types

type Config

type Config struct {
	APIKeys []string `yaml:"api_keys"` // ngrok api keys, one each account // ngrok api 密钥，每账号一个
	Targets []string `yaml:"targets"`  // source domains to rewrite, paired by index with fetched tunnel URLs // 待重写的源域名，按索引与拉来的隧道 URL 一一对应
}

Config holds the YAML config that drives this command

Config 持有驱动本命令的 YAML 配置

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads, parses, and validates the YAML config at the given path Errors when api_keys or targets is missing

LoadConfig 读取、解析并校验指定路径的 YAML 配置 缺 api_keys 或 targets 时报错