Github Enterprise support for garm

[maigl]

We want to use garm with our own private github enterprise instance.
Currently garm does not support this.

Given our last discussions on #29 where you state that
garm should be rather limited and no feature greep: Are you interested to add GHE features ?

[gabriel-samfira]

I would love to add enterprise support. Main problem is, I don't have an account to test with. 😄 My guess is that it should be similar, but I would need a test account with access to an enterprise. Lemme do some research next week.

[maigl]

.. in our setup we needed to update garm:

1. add flag to customize GHE URL
2. depending on url use NewEnterpriseClient .. instead of newClient

this was basically it to get started ..

of course in future we want to add runners on Enterprise level rather then org or repo level. That we have not done so far.

[maigl]

.. added a PR, maybe this could be a starting point #33

[gabriel-samfira]

Proposed a PR here: #37

NOTE: Currently, only the LXD provider is going to work with that PR. I have not tested the external providers. New fields have been added to the bootstrap params that get passed to the external provider, and I have not yet updated the two example providers to use them.

This adds the ability to use your own deployment of GHE Server as well as the ability to add enterprise level pools. I'm still testing it and it still needs some documentation, but it's fairly straight forward to use.

From a UX perspective, to configure garm to use your GHE server, you'll need to add the API endpoint info in the [[github]] section of your config. I've added some brief details on how to do that, here: https://github.com/gabriel-samfira/garm/blob/add-ghe-server-support/doc/github_credentials.md

The base_url and api_base_url are the settings that point garm to your instance of GHE server. Use the ca_cert_bundle option if you have a self signed cert.

This will allow you to create repos, org and enterprises against your own GHE server. Leaving the new options blank, will default to github.com.

Make sure you build both garm and garm-cli. To add an enterprise, use the following command:

garm-cli enterprise add --credentials your_enterprise_creds \
    --name enterprise-name \
    --webhook-secret supersecretWebHookSecret

Adding a pool for an enterprise is similar to adding a pool for an org, but instead of using the --org flag, you'll use the --enterprise flag. Check out the garm-cli help for details.

To make use of the enterprise level runners in your orgs, you will have to go to Enterprise Settings --> Settings --> Hooks to add the hook at the enterprise level. Then you will need to make sure you allow your orgs and repos to use the enterprise level runners in Enterprise settings --> Policies --> Actions. After which the enterprise runners will appear as "Shared" will the selected organizations. You will also have to allow them to be used by visiting the organization Settins --> Actions --> Runner groups and under Shared by the Enterprise click on the Default runner group. Here you'll have to allow the org to use these runners.

More details here: actions/runner#1857 (comment)

Take it for a spin, let me know if it works for you.

[gabriel-samfira]

Also, make sure you use a unique set of tags for pools that respond to a particular workflow from a repo.

For example, you can create a pool at the repo level, one at the org level that the same repo can use, and one at the enterprise level. All three pools are used by the repo, but exist at different hierarchies.

When creating the pools, you should have a unique set of tags. You can have non-unique individual tags, but the set itself should be unique, otherwise garm will get confused about which pool you're targeting.

Example:

• Repo level tags: ubuntu, large, repo
• Org level tags: ubuntu, large, org
• Enterprise level tags: ubuntu, enterprise

In all 3 cases, the ubuntu tag is common. In two cases, the large tag is common, but the sets themselves are unique. If you have more than one pool servicing a repo, in your workflow you should the set of tags, not just one of them.

For example, in your workflow, never use just:

runs-on:
      - self-hosted

Unless you only have one pool configured for that repo (regardless of level in hierarchy).

Instead, use (adapt to your own tags):

runs-on:
      - self-hosted
      - ubuntu
      - enterprise

[maigl]

thanks .. that looks really promising .. I'll check it out asap.

Good job.

[maigl]

.. hey .. we took your PR for a short spin .. on the first glimpse it's looking fine. We'll keep you posted.

Big thanks again.

[gabriel-samfira]

Awesome! Thanks for the update! Will merge the PR as is. Improve on it later.

Feel free to open an issue if you run into any trouble.

By the way, we also added a way to stream logs from the server to the client via websockets. A new command is now available:

garm-cli debug-log

This needs to be enabled in the config: https://github.com/cloudbase/garm/blob/main/testdata/config.toml#L14

and if you're using nginx as a reverse proxu, you'll also need this: https://github.com/cloudbase/garm/blob/main/testdata/nginx-server.conf#L8-L14

Cheers!