GitLab Sync
You use the GitLab integration settings to synchronize your API definition, auto-generated server code, or client SDK with an existing repository on GitLab. The synchronization is made every time you save the API in SwaggerHub. You can fully control which files will be added, updated, or ignored in the target repository.
Supported versions
GitLab.com
GitLab Enterprise Edition v.9.0–10.7.5
GitLab Community Edition v.9.0–10.7.5
In SwaggerHub On-Premise 1.18.4 and later, you can set the default GitLab server in the Admin Center. See Configuring GitLab Integration.
Considerations
GitLab Sync supports OpenAPI 2.0, OpenAPI 3.0 and AsyncAPI 2.x. If you use SwaggerHub On-Premise, note that syncing OpenAPI 3.0 definitions requires v. 1.19.1 or later.
If you use SwaggerHub SaaS and self-hosted GitLab, your GitLab server must be accessible from the public Internet and allow connections from our IP addresses.
You can push the code to:
your own repositories,
repositories owned by the groups and subgroups (organizations) you belong to. You must have the Developer, Master, Maintainer, or Owner role in the group.
Pushing to repositories of other users is not supported.
The target repository must not be empty. It must contain at least one commit, for example, a README or .gitignore file.
If the target branch is protected, your user account or role must have the Allow to push permission on that branch. By default, this permission is granted to the Owner and Masters.
The GitLab Sync configuration is bound to a specific version of the API, so you can synchronize the code for different versions separately.
Configure GitLab Sync
To set up or change GitLab Sync integration, you must be the API owner or a collaborator with the Editor role.
Open your API in SwaggerHub editor.
If the API has several versions, select the version whose code you want to store on GitLab.
Click the API name, switch to the Integrations tab, and click Add New Integrations:
Select GitLab Sync from the list of integrations.
In the subsequent dialog, specify the integration parameters:
Name – Required. A display name for the integration.
GitLab Host – The URL of your GitLab server. Default:
https://gitlab.com. Make sure to include http:// or https:// at the beginning.Personal Access Token – An access token of a user who can push to the desired GitLab repository. Access tokens can be generated on the https://gitlab.com/profile/personal_access_tokens page if you use GitLab.com or http(s)://{gitlab-server}/profile/personal_access_tokens if you use self-hosted GitLab.
Notes:
This token must have the api scope.
You can create a token for your personal account or for a service account used just for integration purposes. In the latter case, this user must have the required permissions to access the target repository.
Important
GitLab tokens can have expiration dates. If a token expires, the integration will stop working until you provide a new token. We recommend that you set a calendar reminder to update tokens before they expire, or use tokens without an expiration date.
Repository Owner – Select the owner of the GitLab repository you want to push the code 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
SwaggerHub 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.
Note: In SwaggerHub On-Premise versions up to 1.23.1, Basic Sync always pushes to the branch named SWAGGERHUB. To use a different branch, select Advanced Sync or upgrade your SwaggerHub On-Premise instance to the latest version.
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 SwaggerHub 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, SwaggerHub 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.
Enabled – Select or clear this check box to enable or disable the integration.
Click Create, then Done.
Push to GitLab
When you are ready to push your changes, click Sync on the editor toolbar, enter a commit message and click Push. SwaggerHub 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 SwaggerHub Editor.
Generate multiple targets
You can add multiple GitLab Sync integrations for different targets. For example, one for the Node.js server, and another for the Android client SDK. You can push all the targets to the same repository, but be sure to use different Output Folders to avoid conflicts.
Disable GitLab Sync
If you no longer want to sync with GitLab, you can disable or delete the GitLab Sync integration. The existing files will remain in your GitLab repository, but SwaggerHub will not update them anymore.
Troubleshooting
If the integration fails with an error, or if the files are not updated in your GitLab repository, make sure that:
The requirements listed above are met. Specifically, the target repository is not empty and the owner of the access token has the necessary permissions.
The access token is valid (not expired or revoked) and has the api scope. If the token is no longer valid, generate a new one and update the token in the integration settings.