GitHub Enterprise Server Sync
This guide is for self-hosted GitHub Enterprise Servers. If you use GitHub.com, see GitHub Sync.
You can integrate Swagger Studio with GitHub Enterprise Server. This allows you to synchronize your API definition, auto-generated server code, or client SDK with an existing GitHub repository. You can fully control which files will be added, updated, or ignored in the target repository.
Optionally, you can configure SSH commit signing. With this setting enabled, GitHub Enterprise Sync sends new commits with a signature, and they appear as Verified in the commit history on your GitHub Enterprise Server. See SSH signed commits below.
Note
Starting from version 2.15, on-premise installations support signed commits for GitHub Enterprise Server and GitHub Cloud when the instance is configured with the GitHub Sync integration.
Requirements
Swagger Studio SaaS
Your GitHub Enterprise Server must be accessible from the public Internet and allow connections from our IP addresses. If this is not possible, use Swagger Studio On-Premise which you can deploy in your own network.
If your GitHub Enterprise Server uses an SSL certificate, it must be issued by a publicly-trusted certificate authority (CA), such as VeriSign, DigiCert, or others.
Self-signed certificates and private CAs are not supported in Swagger Studio SaaS, but are supported in Swagger Studio On-Premise.
Swagger Studio On-Premise
Your GitHub Enterprise Server must be accessible from the Swagger Studio On-Premise server, either directly or via proxy.
Before using the integration, specify the target GitHub Enterprise Server in the Admin Console. See Configuring GitHub Integration.
If your GitHub Enterprise Server uses a self-signed SSL certificate or a certificate issued by a private CA, you need to add it to the trusted certificates on your Swagger Studio On-Premise instance.
Miscellaneous
To configure the integration, you must be the API owner or a collaborator with Edit permissions.
The integration is bound to a specific version of the API and is not automatically copied to new versions. When you add a new version, you need to configure the integration for the new version manually.
Prepare the repository
The target Git repository must not be empty. If it is empty, add at least one file to it, for example, a README or .gitignore file.
Configure GitHub Enterprise Sync
GitHub Enterprise Sync can be configured by the API owner or collaborators with the Editor role.
Open the API page in Swagger Studio.
If the API has several versions, select the version whose code you want to store on GitHub.
Click the API name, switch to the Integrations tab, and click Add New Integrations:
Select the GitHub Enterprise Sync integration.
In the subsequent dialog, specify the integration parameters:
Name – Required. A display name for the integration.
GitHub Enterprise Host – The URL of your GitHub Enterprise Server, for example,
https://ghe.mycompany.com. Make sure to include http:// or https:// at the beginning.GitHub Enterprise Token (or GitHub Token) – A personal access token to authenticate with GitHub. You can create this token on the https://<github-host>/settings/tokens page. The token must have the public_repo scope if the target repository is public, or the repo scope if it is private. For detailed instructions, see Creating a personal access token for the command line.
Click Next in the GitHub Token edit box to continue. Swagger Studio will validate the token and then display other parameters.
Repository Owner – Select the GitHub user or organization that owns the desired repository. The list displays only those accounts your GitHub token has access to.
Repository – Select the repository to push the code to. This repository must not be empty. It must contain at least one commit, for example, a README or .gitignore file.
Sync Method – Select the synchronization type:
Sync method
Description
Basic Sync
Swagger Studio will manage all files in the specified branch and folder: new files will be added, existing files will be overwritten, and unused files will be deleted.
Advanced Sync
Similar to Basic Sync, but you can specify which files will be overwritten or ignored. Use this method if the output folder contains existing files that you want to keep.
Branch – Required. The repository branch to push the code to. If this branch does not exist, it will be created based on the repository’s default branch.
Generated API Code – Required. Select what you want to generate: server code, client SDK, API documentation, or the OpenAPI definition itself as YAML or JSON. See here for a list of supported languages and frameworks.
Tip
To customize code generation options, such as package names, use the Export > Codegen Options menu in the Swagger Studio editor. See Code Generation Options for details.
Output Folder – The output folder for the generated code, relative to the repository root. For example, server or sdk/android. If this folder does not exist, it will be created. If the output folder is not specified, Swagger Studio will create files and folders in the repository root.
Important
Use forward slashes (
/) as path separators:folder/subfolder1/subfolder2 – Correct
folder\subfolder1\subfolder2 – Incorrect
Paths – Available only if you selected Advanced Sync. Use these options to control which files and folders will be created, updated, deleted, or ignored during synchronization. All the paths are relative to the Output Folder. You need to specify either Partially Managed Paths or Fully Managed Paths.
Partially Managed Paths – These files and folders will be created if they do not exist, but the existing files and folders will not be modified. The wildcard
*indicates all files and folders in the Output Folder.Fully Managed Paths – These files and folders will be completely managed by the integration: new files will be added, the existing files will be overwritten, and the files that are no longer used will be deleted. You can use
*as a wildcard for all files.Ignored Paths – These files and folders will remain as is and will not be changed in any way.
Important
Use forward slashes (
/) as path separators, for example, sdk/android/README.md.Output file – Only used if Generated API Code is JSON or YAML, that is, the OpenAPI definition itself. Specifies the name of the .json or .yaml file to create, for example, swagger.yaml or petstore.json. This file will be created in the Output Folder.
SSH Signed Commits – Optional. Select the Sign commits with SSH checkbox to enable cryptographic signing for all commits pushed by this integration.
Important
An owner or admin of your Swagger Studio organization must configure a signing identity before you can use this option. If the signing identity is missing, the check box is unavailable. See Generate the organization key below.
Enabled – Select or clear this check box to enable or disable the integration.
Click Create, then Done.
SSH signed commits
When SSH commit signing is enabled, every commit pushed to your GitHub Enterprise Server through this integration is signed with an SSH key pair that Swagger Studio generates for your organization, and it displays a Verified badge in the repository's commit history. This is useful for repositories that require a signature on every commit.
Keep the following in mind:
The key pair is generated once per organization, not once per integration. All GitHub Enterprise Sync integrations in the organization sign commits with the same pair.
Only the public key is shown to you. Swagger Studio stores the private key and uses it to sign commits.
Signing is optional for each integration. Generating the key does not change the behavior of integrations that have the option turned off, and commits that already exist in the repository are not affected.
The feature is only available to organizations on the Enterprise plan. To configure it, you need access to the organization settings, where you generate the key and set the signing email, and an account on your GitHub Enterprise Server whose email address is associated with the signature, and to which you can add a signing key.
This applies to GitHub Enterprise Sync only. If your host is https://api.github.com, use the GitHub Sync integration instead.
Generate the organization key
Only an organization owner or administrator can configure the signing identity.
To generate the signing key pair for your organization, do the following:
On the Organization Settings page, locate the GitHub Enterprise Sync: SSH Signed Commits section. If the organization does not have a key yet, the section prompts you to generate one.
Select Generate key.
The Generate key dialog box opens.
In the GitHub account email input, enter the email address of the GitHub Enterprise Server account that will hold the signing key.
Select Generate to create the key pair.
The Generate key dialog box closes. Swagger Studio generates the keys and stores the private key encrypted. The SSH public key now displays in the GitHub Enterprise Sync: SSH Signed Commits section.
Select the copy icon next to the SSH Public Key value for use in GitHub Enterprise.
Add the public key to GitHub Enterprise
GitHub requires the SSH public key to verify a signature. Add the key as a signing key to the GitHub account whose email address you specify as the signing email in Swagger Studio.
To add the public key, do the following:
In your GitHub Enterprise Server, open the settings of the signing account and select SSH and GPG keys in the sidebar.
Click New SSH key to add a key.
In the Key type list, select Signing Key, then paste the public key you copied from Swagger Studio.
Click Add SSH key to save it.
Important
Authentication keys and signing keys are separate in GitHub. A key added as an authentication key lets Swagger Studio push, but GitHub does not use it to verify signatures. If commits arrive as Unverified, check the key type first.
Enable signed commits for an integration
To enable signed commits for a GitHub Enterprise Sync integration, do the following:
Open the API definition in Swagger Studio editor.
Select the API name, switch to the Integrations tab, and then select your GitHub Enterprise Sync integration. To add a new integration instead, select Add New Integrations, and then select GitHub Enterprise Sync.
In the integration configuration dialog box, go to the SSH Signed Commits section.
Select the Sign commits with SSH check box.
Select Save, and then select Done.
Swagger Studio signs every commit that this integration pushes from now on. Commits that already exist in the repository are not affected.
To confirm that signing works, save the API to trigger a sync and open the new commit in your GitHub Enterprise Server. A signed commit displays the Verified badge next to the commit message.
Push to GitHub
When you are ready to push your changes, click Sync on the editor toolbar, enter a commit message and click Push. Swagger Studio will generate the specified target (server code, client code, API documentation or an OpenAPI JSON or YAML file) and push it to the configured repository and branch.
Commits are made on behalf of the user associated with the access token. If synchronization fails (for example, due to a permission problem), you will see an integration error at the top of the Swagger Studio Editor.
Disable GitHub Enterprise Sync
If you no longer want to sync with GitHub, you can disable or delete the GitHub Enterprise Sync integration. The existing files will remain in your GitHub repository, but Swagger Studio will not update them anymore.
Troubleshooting
If the integration fails with an error, check the access token expiration date. If it is about to expire, generate a new token and update the token in the integration settings. If the token has expired, generate a new one and create the integration anew.