Many enterprises are looking to combine the benefit of Git-based repos with company requirements of on-prem code hosting. Today's GitHub announcements of a number of new enhancements to GitHub Enterprise are a great step forward for enterprise-grade repos in an on-prem world. Shippable supports GitHub as both a service as well as the on-premise GitHub Enterprise. Here are instructions to connect Shippable to GitHub Enterprise.
Before you start…
- A GitHub.com account is required to sign up for Shippable with GitHub Enterprise. We are working on OAuth/LDAP authentication with GitHub Enterprise and this will be available in a future milestone.
Step 1: Sign in and add account integration
- Go to shippable.com
- Sign in with your github.com or bitbucket.com account. You will not need a credit card to sign in.
- Go to Account Settings by clicking on the gear icon on the top right of your Shippable dashboard.
- Click on the ‘Integrations’ tab and then click on the ‘add integrations' to add a new integration.
- Name your integration with a friendly name. This friendly name will be how users in your organization will see this integration for use in their projects. Then choose ‘GitHub Enterprise’ from the dropdown for ‘Master Integration’.
- Enter the URL for your GitHub Enterprise instance – https://(hostname)/api/v3
- For the token, you’ll need to log in to your GitHub Enterprise account, go to Settings -> Personal Access Tokens, and generate a new token. Give the token the following permissions –
- Copy the generated token and paste it into the Token field of the Shippable UI.
- Click on ‘Save’ to save your GitHub Enterprise integration.
Step 2: Sync the account
- Click on the ‘Accounts’ tab in Account Settings.
- You will see an option to Sync your account. Click on it and wait until the spinner stops.
- Navigate back to your account dashboard by clicking the Shippable logo on the top left.
- Expand the CI dropdown. You should see your GitHub Enterprise organization(s) in the dropdown.
Step 3: Get the Shippable Single Tenant CI Plan (Free while in Beta)
- In the CI dropdown, click on the organization that has the repositories you want to enable.
- If you’re not automatically redirected to the Billing tab, click on the Gear, then select the Billing tab.
- Choose the st-ci-beta plan. This is our Single Tenant plan and is required for GitHub Enterprise support.
- Choose the number of build minions you need. Number of minions = number of parallel builds you can run on Shippable.
- Enter an email address where you want to receive invoices.
- Enter your credit card information. You will not be charged anything during the beta program. At the end of our beta, we will reach out to you with a reminder before we charge your card. Approximate pricing at launch for the number of minions you choose is provided on this screen.
- Click on Buy.
Step 4: Attach your build host(s)
After signing up for the single tenant plan, you should be redirected to the Settings page. You can add a node from here. If you are not redirected for some reason, click on the ‘Settings’ gear to the right and add a node.
You can use any machine to be your build host(s). All your builds will be run on your machines and no other customers’ builds will run on your machines. The minimum requirement for a build host is 30GB HDD, 2GB RAM, and 64 bit OS. We have tested on Ubuntu 14.04 so that is the recommended OS. There is no CPU constraint.
Once your build hosts are attached, everything works pretty much like it works on our platform today. You can enable projects and run builds as long as you have a valid shippable.yml at the root of the repository you want to build.
Step 5: Team access to build informationNow your entire team can use Shippable against your GitHub Enterprise environment. One note: everyone in the org who wants to look at builds on Shippable will need to follow steps 1 & 2 above. They will see the organization in their CI dropdown and they can then view build information.
TROUBLESHOOTING & TIPS
Here are some tips to help you get your GitHub Enterprise to Shippable connection up and running quickly:Problem: Build fails with a certificate related problem in git_sync step
Solution: This happens when the SSL certificate you have set up on the server is not recognized as valid by git. This issue only happens for public projects since we use the https URL to clone public projects. You can do one of the following (in order of preference):
- Use a recognized cert
- Update the CA certificate store in the image you're using so it recognizes the issuer of your SSL cert (see http://stackoverflow.com/questions/21181231/server-certificate-verification-failed-cafile-etc-ssl-certs-ca-certificates-c for details)
- Add the following env to your YML file:
env: - GIT_SSL_NO_VERIFY="1"
Problem: Build fails for public projects at the git_sync step
Solution: You can do one of 2 things –
- Turn ‘Private Mode’ to OFF in the GitHub Enterprise Management Console, or
- Make the project in question private through its GitHub Settings. You will need to ‘Sync’ and ‘Reset’ the project in the projects settings tab on Shippable.
This is again a side effect of us using https to clone the repository. We’re working on removing this limitation.
Tip #1: If you want to build public repositories on Shippable, you will need to set ‘Private mode’ to OFF in your GitHub Enterprise management console. This means that your public repositories will be viewable by anyone with access to your GHE instance and has link to them or goes to https://(hostname)/explore. We are working to remove this requirement, so let us know if this is important to you and we’ll make it a priority.
Tip #2: Any time you change repository settings from private to public or vice versa, you should ‘Sync‘ and ‘Reset’ the project on Shippable before running the next build.