Creating your first plugin documentation

[chrischu]

I would really like some more detailed configuration. Especially as it comes to "plugins" (configuring them, creating them, etc.).

With the current documentation I'm not sure if the project is useful for my intended purpose: We want to automate some Git processes (e.g. tagging commits) but since those run in an automated fashion (on our build agents) we want to limit what these automated processes can do (e.g. only push tags).

Is that possible with Git Proxy? If so, could you provide some example configuration how?

[maoo]

Good day @chrischu , and thank you for raising this issue!

As git-proxy adopters, I'd defer to @msagi @coopernetes and @JamieSlome to comment on the use case you propose.

In parallel, I wonder if you'd be able to join one of our bi-weekly meetings (bi-weekly, Monday 11am EST) and/or our Slack channel (finos-lf.slack.com , feel free to email [email protected] and we'll invite you), so we can iterate a bit more on your proposed use case.

Last, it's worth mentioning that the support for Git Proxy plugins is expected to be consolidated and documented in our 2.0 version; you can find a proposal on https://github.com/finos/git-proxy/issues/425#issuecomment-1912528778 ; we'd love to hear your feedback!

Thanks!

[chrischu]

Thanks for the quick reply!

I sent an email to [email protected] for the Slack channel invite. I think that's a good first step, but if necessary and helpful, I could also join the meeting in one of the coming weeks :).

[JamieSlome]

@chrischu - are you happy to rename this issue to Creating your first plugin documentation? We discussed in our community call yesterday that this is critical for new adopters to quickly play with GitProxy and easily grasp its potential.

[JamieSlome]

@coopernetes - am I right in saying that the user can set their packages ENV variable, and thus create a packages folder in their local directory to then start spinning up new plugins? Want to get this ticket out ideally before or just after OSFF.

[coopernetes]

@coopernetes - am I right in saying that the user can set their packages ENV variable, and thus create a packages folder in their local directory to then start spinning up new plugins? Want to get this ticket out ideally before or just after OSFF.

The current implementation uses an environment variable to read in a list of file paths which are loaded dynamic as Node modules (await import('path/to/file.js')). The PluginManager is not opinionated as to where these files are located, it's just an arbitrary file path on disk where the git-proxy process is running.

I'm looking at enhancing this feature to make it a bit more intuitive such as the ability to load plugins as packages which are directly installed under git-proxy's node_modules/ directory. This would allow a plugin author to create a npm package, pull it into their own git-proxy deployment just like any other dependency.

I also want this exposed via configuration (proxy.config.json) and not just via environment variables since we can apply some amount of schema validation on the config file.

[JamieSlome]

@coopernetes - is there any chance you could add this description and the steps a developer needs to take to create their first plugin into the docs (which will close this issue)?

The current implementation uses an environment variable to read in a list of file paths which are loaded dynamic as Node modules (await import('path/to/file.js')). The PluginManager is not opinionated as to where these files are located, it's just an arbitrary file path on disk where the git-proxy process is running.

I'll then run through the docs and test the flow 👍 Can also help clean up the docs and find a suitable home for the walkthrough. Just a rough estimation even of the steps would be really helpful 👐

[coopernetes]

Expect a PR shortly on this. I've completed the new content to the doc. In the process, I realized the plugin system was not very robust or user-friendly & needed some overhauling. It was not suitable for use IMO so there will be marked improvements raised in the same PR.

Completed:

• [x] add a new Development section on the docs which includes:
  • [x] documenting how to use and develop plugins (+ new extension points)
  • [x] skeleton of a contributing page
• [x] new extension points + tests
• [x] working POC internally using our private fork (this was necessary since the plugins rely on npm packages and had to publish copies of the various packages to prove out the implementation)

Outstanding:

• [x] strip our internal company details & review
• [x] create the PR here for feedback

[JamieSlome]

@coopernetes - amazing. Super super excited 🎉

You are a rockstar (hands down).

[JamieSlome]

@chrischu - you're going to love what @coopernetes has been up to.

Would love to get your thoughts and feedback (currently in dev mode https://github.com/finos/git-proxy/pull/713). You can check out the docs in dev mode here:

https://deploy-preview-713--endearing-brigadeiros-63f9d0.netlify.app/

[coopernetes]

Docs are live: https://git-proxy.finos.org/docs/development/plugins

[JamieSlome]

Closing the issue 👍 You did a smashing job, Thomas!

@chrischu - thank you for pointing us in the right direction ❤️ Let us know if anything in the documentation requires improvement or iteration.