Intro
It is necessary to understand basic principles. There is either generic Git support with basic Git functionalities but without any advanced integrations like merge requests, branches and so on.
You have to choose proper way based on available options. If GitLab is hosting intended repositories, you shall use GitLab auto-connect in Jira Git plugin. Use generic Git connect only in custom and edge cases.
Recommended setup:
service account available for integration purposes
Personal accounts are NOT recommended because integrations usually fail when person changes credentials or leaves the project/company.
- do not use service accounts with huge amount of repositories access as the sync can/will use lot of Jira server storage
- in case of custom/generic repositories limit the projects that will use every specific repository otherwise it can be security issue
GitLab repositories integration
How does it work:
- service account needs to be created in GitLab
- personal access token must be generated for that service account in GitLab
- access to proper repositories must be granted to this service account
- Jira admins shall setup integration using service account credentials
Getting service account in GitLab
These instructions are made for TDS users. Getting service account into your local GitLab installations will be similar in principle, however you need to adapt them on your environment.
Preparing service account in TDS GitLab by end users
- Make sure you have credentials for service account, if not, reset them in portal following steps described in Project Details#ServiceAccount
- Add service account into proper repositories using portal
- Open inkognito/private window
- Login to GitLab using service account credentials
- Then go to Personal Access Tokens page https://gitlab.shared.CUSTOMERX.tds.tieto.com/profile/personal_access_tokens
- Fill the name , for example like "jira-integration"
- Leave Expires at EMPTY to keep it unlimited depending on project needs
- Choose "api,read_user, read_api, read_repository, write_repository"
- Copy generated token for later use
- Verify that account can access desired repositories
- Send request to TDS team with relevant information:
- service account token
- GitLab URL
- Jira project URLs with KEYs that you need to integrate this GitLab with
Preparing service account in TDS GitLab by TDS support/consultancy team
- Add service account into proper repositories using portal
- Go to GitLab users list https://gitlab.shared.CUSTOMERX.tds.tieto.com/admin/users
- Search for that service account and open it by clicking username or simply go to user profile using this direct link while replacing XXX with username - https://gitlab.shared.CUSTOMERX.tds.tieto.com/admin/users/XXX
- Click "Impersonate"
- Then go to Personal Access Tokens page https://gitlab.shared.CUSTOMERX.tds.tieto.com/profile/personal_access_tokens
- Fill the name , for example like "jira-integration"
- Leave Expires at EMPTY to keep it unlimited depending on project needs
- Choose "api,read_user, read_api, read_repository, write_repository"
- Copy generated token for later use
- Verify that account can access desired repositories
- Stop impersonation
Setting Git integration in Jira by administrators
- Go to https://jira.shared.CUSTOMERX.tds.tieto.com/secure/ViewGitRepositories.jspa
- Click GitLab in auto-connect options
- Provide GitLab URL
- Enter access token generated in previous step
- Click Next and check loaded projects/repositories list to see whether accesses are correct and make sure to fix it
- Click Continue
- Untick "Associate with all projects" and choose proper Jira projects to map selected repositories to
- Or enable PAT for users interactions with GitLab which is even better but can be very confusing and complex for users
- Click Finish
- Find newly created integration
- Click gear next to it and select "Edit integration connection settings"
- Change "Display Name" from GitLab URL to service account username and something which represents that integration, usually portal project name, for example "srv123abc - MyPortalProject"
- Click Update
Generic Git repositories integration
- service account is recommended to be created in remote Git solution
- SSH key, username and password or personal access token must be generated for that service account
- access to proper repositories must be granted to this service account
- Jira admins shall setup integration using provided service account credentials and all required repositories one by one
Integrate GitLab project into Jira
- Go to you GitLab project settings, URL shall be like https://gitlab.shared.CUSTOMERX.tds.tieto.com/PORTAL-PROJECT-NAME/GitLab-PROJECT-NAME/-/services/jira/edit
- Enable it (Active ~ true)
- Select triggers and actions feasible for you
- Enter Jira Web URL, for example https://jira.shared.CUSTOMERX.tds.tieto.com
- Leave "Jira API URL" empty as TDS provides REST api on standard endpoints. If you have some different NON TDS Jira, you might need to specify this REST API URL.
- Username or Email - recommended is username of your project dedicated service account, which is described in Project Details#ServiceAccount
- Password or API token - recommended is token of your project dedicated service account, which is described in Project Details#ServiceAccount
More details can be found in GitLab documentation https://gitlab.shared.pub.tds.tieto.com/help/user/project/integrations/Jira