Swift-package-collection-generator: support GitHub Enterprise?

I was excited by the new package collection feature that was added with Xcode 13. My team maintains a good amount internal frameworks hosted on a GitHub Enterprise instance, but these can be hard to discover for others. Seems to me a perfect match for the use of a package collection :+1:

So I decided to give the package-collection-generator a try, but quickly encountered some snags - the generator so far seems to be purely intended for use with repos located on GitHub.com. I'm not aware of all the differences between on-prem GitHub and GitHub Enterprise, but from what I can see it comes down to this:

  • the API URL is <host>/api/v3 vs. api.github.com
  • auth via personal access tokens seems to be done with basic auth (base64 encoded user:token) vs. "Authorization: token "

The actual API responses seem to be the same. I've gone ahead and added barebones support on my fork here, but it's very limited as it relies on the a new token type, githubEnterprise to infer if a host is GitHub Enterprise or not. If that's not passed as an argument then it will default to the GitHub.com api format, and fail.

At this point I have something that works for my team, but if this were to be officially supported I think more significant changes have to be made - too much for me to feel could be done without seeing what the maintainers and the community think. For proper support we might want some extra configuration flag/enum in the input json to specify where a repo is hosted so the code can determine what API format to use. This could be used in the future to add support for other cloud git providers like BitBucket. That however, would be some effort with shuffling code around (I've got some ideas here, though).

So, my questions would be as follows:

  • Is GitHub Enterprise support for the generator something folks would be interested in, and is it a direction it as a tool should go in?
  • The code is already set up with extensibility in mind, perhaps this is already planned?
2 Likes

I believe you are correct and the generator makes some assumptions about github.com to retrieve some of the optional metadata. However, that should be optional / best-effort attempt to retrieve additional metadata which is not critical to the toolโ€™s ability to generate the collection.

In case you want to help โ€œteachโ€ the tool to retrieve metadata from additional SCM system such as github enterprise, PRs are welcome :pray:

cc @yim_lee

Thanks @swild for giving the generator tool a try.

I am not sure these are true for all GitHub Enterprise instances, at least from personal experience GHE supports api.<host> API URL and Authorization: token header.

Yes. I wasn't aware there are differences in calling GitHub vs. GitHub Enterprise APIs so the implementation doesn't make a distinction, but the intention is to be able to make use of GH API in general.

I think this approach makes sense, though I still believe/hope the current code works for GHE as well. I would be interested to know if the difference is caused by GHE version or configuration.

Thanks for your responses guys!


I think you're right. I'm not too familiar with GitHub's solution stack but there also is a GitHub Enterprise Cloud solution that appears to use the standard api.github.com endpoint (docs here). GitHub Enterprise Server (self-hosted) is the one that I focused on. That one uses the <host>/api/v3 format (docs here)

It does - the API format/response seems the same - I think the difficulty is going to be how to determine what host matches with what kind of GitHub "type" (GHE vs GH).

The tricky bit as well is that GHE can be heavily customized. The part where my logic with the new token type falls flat is if you do not need a token to call the API or clone repositories, the modified tool does not know what API endpoint style to use.
In my experience, some self-hosted GHE instances are locked down to a point where even a simple git clone of a public repo needs authentication - which will give the generator trouble as it will get stuck after the git command asks for a username. This can be worked around with git-askpass but feels clunky and insecure. I'm not convinced that this is something the generator should worry about though.


I'll research some more and see what makes the most sense, if I'm happy with something I'll raise a PR :D

1 Like