search

github-community-projects / private-mirrors

A GitHub App that allows you to contribute upstream using private mirrors of public projects
MIT License
125 stars 13 forks source link

"Headless" ICF - API access to functionality #120

Open ahpook opened 4 months ago

ahpook commented 4 months ago

Is your feature request related to a problem?

Some users are working to integrate ICF into a larger "open source portal" context, where they already have a web app and additional tooling around OSS contributions (like which projects are available for contributions, who is allowed to contribute, etc). They'd like to make use of the internals of ICF - the mirror lifecycle management and synchronization - but wrap this in their own web service.

Describe the solution you'd like

The goal would be to make ICF "embeddable" in other applications. @ajhenry brainstormed a couple of options like creating a RPC client, making the app "import"-able as a package, or having a separate web service from the front end which could be called by another app. Not sure which has the highest effort/reward and would best meet the user need, so this requires more exploration and thought.

Describe alternatives you've considered

No response

Additional context

No response

Miablo commented 1 month ago

Some users are working to integrate ICF into a larger "open source portal" context, where they already have a web app and additional tooling around OSS contributions (like which projects are available for contributions, who is allowed to contribute, etc).

For Private Mirrors to have a 'headless' API functionality some of the workflows would change when the currently coupled UI is replaced with the user's larger 'open source portal', right?

Would this issue describe the creation of a stand-alone API that can then be onboarded internally by a team who does have that internal facing portal? The assumptions made here are that the user would:

  1. have a db or some system of record of who is allowed to contribute
  2. have a db or system of record of what projects can be contributed to
  3. have a list of licenses or other parameters that will need to be checked prior to allow a contribution be made to a repo
  4. require new user registration would be handled by the existing 'open source portal'
  5. have SSO integration would be used instead of the OAuth w/ GitHub method used by the current application to verify the user's identify and then verify their access to the various orgs

Currently there are four routers:

  1. Config
  2. Git
  3. Repos
  4. Octokit

I would assume that these would become the end points or callable routes in this API? Would some additional functionality be useful for audit and/or compliance checks? (--Just starting to think out loud here--)

ahpook commented 1 month ago

@Miablo thanks for the write-up!

For Private Mirrors to have a 'headless' API functionality some of the workflows would change when the currently coupled UI is replaced with the user's larger 'open source portal', right?

Yes I think that's exactly right, and as you say at the bottom the different routers would become callable separately, just to execute the functionality they are responsible for, and the larger user auth/authz would be externalized since it's likely different for everyone.

Miablo commented 3 weeks ago

@ahpook What do you envision for this implementation? Are you ya'll locked in on using tRPC or would you all be open to using something like:

  1. DeepKit
  2. NestJs withfastify
  3. or anything else that may be a good fit

I'm trying to think through the scope for this specific issue and it would make sense to have one issue (this current one) to create the API itself and then other new issues, if ya'll want, to create a solo component for the UI and a solo component for the web hooks.

I see priviate-mirrors as, at least, 3 potential products:

  1. private-mirrors full app (UI, API, Webhooks) -- current state
  2. private-mirrors API
  3. private-mirrors Webhooks

This would then create separate consumable components of private mirrors or provide the full functioning app as well as an option for consumers to pick and choose their solution.

What are your thoughts?

ahpook commented 2 weeks ago

Hi Mio, I am but a simple product manager and don't have implementation opinions. I do think it'd be great to have small implementation steps that iterate towards the end state, and if creating separate issues to track that works best for you, go for it! 👍

Splitting it out as you describe is fine with me as long as there's an easy way for people to get started. The most common use case would be someone who wants the full app as an 'all in one' setup, so installing the UI should pull the other pieces in.

Miablo commented 2 weeks ago

Thank you, thank you for the keys to the kingdom! 😁 I will create a proposed API design doc / diagram to toss in here for review.