Configure GitHub Integration

Note: This information applies to Swagger Studio On-Premise.

GitHub integration enables the following features in Swagger Studio On-Premise:

GitHub Sync integration,
user sign-in and login via GitHub.

Swagger Studio On-Premise supports both GitHub.com and GitHub Enterprise Server.

Prerequisites

To set up GitHub integration, you must be an organization owner in GitHub and an admin in Swagger Studio.

Considerations

If your Swagger Studio On-Premise instance is accessible from the public Internet and uses GitHub.com as the authentication method, anyone who has a GitHub.com account – including people outside your company – will potentially be able to log in to Swagger Studio.

This is not a concern when hosting Swagger Studio On-Premise behind a firewall or when using GitHub Enterprise Server.

In GitHub

First, you need a GitHub client ID and a client secret. To get them, follow these steps to register Swagger Studio as an OAuth application on GitHub:

Log in to GitHub as an owner of your GitHub organization.
Click your profile photo and select Settings from the menu.
In the sidebar, under Organization settings, click your organization.
In the sidebar, click OAuth Apps (if you use GitHub.com) or OAuth applications (if you use GitHub Enterprise Server).
Create a new OAuth application.
Enter the following:
- Application name –Swagger Studio
- Homepage URL – http(s)://{SWAGGERHUB}
- Authorization callback URL – http(s)://{SWAGGERHUB}/apiproxy
Replace {SWAGGERHUB} with the domain name or IP address of your Swagger Studio On-Premise instance. Use https:// if SSL access is enabled, otherwise, use http://.
Click Register application.
Copy the generated Client ID and Client Secret.

In Swagger Studio On-Premise

Open the Admin Center.
Select Settings > Integrations on the left.
Configure the settings as described below.
GitHub.com
You need to specify only the client ID and secret. The other options are pre-filled, but we provide the values below for reference:
- Authentication Type – To enable user authentication via GitHub, use of the following authentication types:
  - Internal_and_GitHub (default) – both built-in authentication and GitHub authentication can be used.
  - GitHub – authentication via GitHub only. Built-in authentication is disabled.
  Note
  GitHub authentication is incompatible with SAML and LDAP single sign-on.
- GitHub UI location – https://github.com
- GitHub API URL – https://api.github.com
- GitHub Client ID and GitHub Client Secret – Paste the client ID and client secret that you generated earlier.
- GitHub Authorization Endpoint – https://github.com/login/oauth/authorize
- GitHub Token Endpoint – https://github.com/login/oauth/access_token
GitHub Enterprise Server
- Authentication Type – To enable user authentication via GitHub, use of the following authentication types:
  - Internal_and_GitHub (default) – both built-in authentication and GitHub authentication can be used.
  - GitHub – authentication via GitHub only. Built-in authentication is disabled.
  Note
  GitHub authentication is incompatible with SAML and LDAP single sign-on.
- GitHub UI location – Your GitHub server URL, for example, https://ghe.MyCompany.com or http://10.10.10.10:8080.
- GitHub API URL – http(s)://{GITHUB-SERVER}/api/v3
- GitHub Client ID and GitHub Client Secret – Paste the client ID and client secret that you generated earlier.
- GitHub Authorization Endpoint – http(s)://{GITHUB-SERVER}/login/oauth/authorize
- GitHub Token Endpoint – http(s)://{GITHUB-SERVER}/login/oauth/access_token
Replace {GITHUB-SERVER} above with your GitHub server domain or IP address.
Click Save Changes and Restart.
In v. 1.19.1 or earlier, click Save Changes, then switch to the System page and click Restart Swagger Studio.
Wait a few minutes for the system to restart completely.

Using GitHub Integration

GitHub Sync integration will now work with the GitHub server you chose – GitHub.com or GitHub Enterprise Server.

Additionally, if you use GitHub authentication, users will be able to create Swagger Studio accounts using GitHub and to link their existing accounts to GitHub.