Setting up the Git Repository
IBM Industry Solutions Workbench gives the flexibility to connect to one or many Git providers. Using these Git providers, one has the possibility to decide with every microservice, where the modelled data and the implemented code should be stored. The permissions that are defined at the Git provider will be automatically applied to the Solution Designer and therefore full control over the available capabilities for the users is guaranteed.
About Git Providers
Admin users can manage the available Git providers in the Admin Settings area. Before creating a microservice, the Git provider has to be defined there. Each Git provider is identified by a unique alias.
The supported Git provider types are:
- GitLab (self-managed)
- Bitbucket Server
- GitHub (Enterprise)
Use Git Providers
To use a Git provider, every user has to define an access token for the Git. All supported Git providers provide the possibility to create these personalized access tokens. Each user can only specify one token per provider. This token will be from then on used for every interaction with the remote Git and also to restrict the capabilities of the user to the permissions that are set in the remote Git repository.
Use Multiple Git Providers
If microservices should be stored at different places, an admin user can define multiple Git endpoints. While creating a microservice, the creator could define, where the microservice should be stored. Also, a specific group could be specified while creation. These groups are usually used to restrict permissions on certain microservices for dedicated users.
Manage Git Providers
In order to create and manage Git providers you must have admin privileges. To access the Admin Settings page use the Settings capability on the top right of the page. There you will get an overview of the already existing Git providers and their master data.
Create Git Provider
To create a new Git provider use the Create capability.
The master data of a Git provider consists of:
- Alias: Used to specify a Git provider under the given alias name (required)
- Type: The Git provider platform. There are three options: GitHub Enterprise, GitLab and Bitbucket Server ( required)
- Base URL: The URL to the Git provider. This value must be unique (required)
- Label: Short description of the Git provider (optional)
- Read-only Git provider: Used to mark the Git provider as read-only. Read-only Git providers can not be used to create new projects. Projects can not be exported to asset catalogs using read-only Git providers.
Edit Git Provider
Admin users can edit the Git provider for any record in the application within the Admin settings. Here, the label can be edited and if the Git provider is read-only or not.
Delete Git Provider
To delete a Git provider use the header or inline Delete capability. After confirming the action, the Git provider and all tokens related to it will be permanently deleted.
You are not allowed to delete a Git provider if there are still microservices in the Solution Designer associated to the specific provider.
Necessary Git Token Permissions
The available capabilities in the Solution Designer depend on the permissions that are assigned to the user in the remote Git.
Grant General Permissions for Users on Repositories
Repository or group administrators on the remote Git are responsible to grant access permissions on the repositories for the actual users.
GitLab:
- To create new microservices: at least developer permissions on the group must be granted.
- To edit the microservice content: at least developer permission (on the group or the repository) must be granted.
- To view the microservice: at least guest or reporter permission (on the group or the repository) must be granted.
- To delete a microservice: at least owner permission on the group must be granted.
The above described permissions are valid for a GitLab EE default setup. If an installation has additionally specific restrictions on the repositories and groups, the granted permissions might have to be different.
Bitbucket Server:
- To create new microservices: administrator permission on project must be granted.
- To edit the microservice content: at least write permission (on the project or the repository) must be granted.
- To view the microservice: at least read permission (on the project or the repository) must be granted.
- To delete a microservice: administrator permission on project or repository must be granted.
The above described permissions are valid for a Bitbucket default setup. If an installation has additionally specific restrictions on the repositories and groups, the granted permissions might have to be different.
GitHub Enterprise:
- To create new microservices: The authenticated user must be at least a member of the GitHub organization.
- To edit the microservice content: at least write permission in the GitHub organization must be granted.
- To view the microservice: at least read permission in the GitHub organization must be granted.
- To delete a microservice: admin access on the organization must be granted.
The above described permissions are valid for a GitHub Enterprise default setup. If an installation has additionally specific restrictions on the repositories and groups, the granted permissions might have to be different.
Define Specific Permissions on Tokens
Usually, one could explicitly define the basic permissions for the token while creating the token in the remote Git provider.
Minimum permissions that need to be granted for the token:
GitLab:
- Select scope
api - Select scope
read_repository - Select scope
write_repository(for GitLab version 11.11 or higher)
Bitbucket Server:
- Select permission "Read" for basic read access
- Select permission "Write" to allow create, delete and edit capabilities, as well as committing to the repository
- Select permission "Administrator" to allow create, import and delete microservices
GitHub Enterprise:
- Select permission "public_repo" to access public repositories.
- Select permission "write_org" to read and write organization and team membership, read and write organization projects.
- Select permission "repo_status" to access commit status in a repository.
- Select "delete_repo" to be able to delete organization repositories.
- Select "admin_org" to get full access of organization and teams, read and write organization projects.
Manage Git Tokens
To access the User Settings use the Settings capability on the top right of the page and navigate to the User Settings page.
Create a Git Token
Each user can have only one token for each Git provider for which he has rights. To create a new token use the header capability Create in the Git tokens tab on the User Settings page.
A Git token is defined using the following master data:
- Token name: Name of the token. (required, unique for each user)
- Git provider: List of all Git providers for which the current user has access permission. The Git providers are represented with their assigned alias that was provided by the admin user (required)
- Git access token: The actual Git token (required)
- Git username: The username as defined in the Git provider (required)
By using the default Verify and Create the provided Git username and Git access token will be validated before the creation. In case of incorrect data you will get an error notification. If you want to use that data anyway please choose the Create button.
Verify a Git Token
To verify a Git token use the inline or header Verify capability. You will get either a "Success" or an "Error" notification displayed.
Delete a Git Token
To delete a Git token use the inline or header Delete capability. After you confirm the action the Git token will be permanently deleted.
Update a Git Token
In order to update a Git token use the inline or header Edit capability. This action only allows a change of the access token itself. If your username has changed delete the previous Git token and create a new Git token for the same Git provider. After saving the changes, all Pipeline Configurations using your personal credentials will also be updated.