The sync tool uses web hooks and Jira REST API to perform the one way sync of upstream Jira to the downstream one. User actions in the upstream Jira trigger web hooks, which send the events to the sync tool. Sync tool uses the REST API to get the required information from the upstream Jira and sends it over to the downstream one.
In the upstream Jira (the source/original) configure a webhook per project you want to be synced.
The tool listens for a web hook events at /api/jira/webhooks/{PROJECT-KEY}
.
Set up the secret, while creating the web hook so that the requests could be signed and checked, see https://developer.atlassian.com/cloud/jira/platform/webhooks/#secure-admin-webhooks. If secret was configured on the web hook side, signature verification can be enabled per project through:
jira.project-group."project-group-name".projects.PROJECT-KEY.security.enabled=true
jira.project-group."project-group-name".projects.PROJECT-KEY.security.secret=secret-you-have-specified-in-the-web-hook
See also:
This tool requires two accounts provided per project group. One account is to access the upstream Jira while the other one is for the downstream Jira.
Users are specified in the project group configuration in the application.properties
file:
jira.project-group."project-group-name".source.api-uri=https://your-upstream-jira-instance/rest/api/2
# if the Jira instance works with Basic authentication then username/PAT should be supplied:
jira.project-group."project-group-name".source.api-user.email=your-user-name-of-service-a-user
jira.project-group."project-group-name".source.api-user.token=your-personal-auth-token-for-the-above-user
jira.project-group."project-group-name".destination.api-uri=https://your-downstream-jira-instance/rest/api/2
# if the Jira instance works with bearer tokens only, and basic auth is disabled,
# specify the login kind and provide PAT:
jira.project-group."project-group-name".destination.login-kind=BEARER_TOKEN
jira.project-group."project-group-name".destination.api-user.token=$your-personal-auth-token-for-the-service-user
Please see the JiraConfig
javadocs for more details on the configuration properties.
See also:
With users configured the next step would be to define the projects and how they are mapped.
jira.project-group."your-project-group".projects.YOUR-SOURCE-PROJECT-KEY.project-id=downstream-project-id
jira.project-group."your-project-group".projects.YOUR-SOURCE-PROJECT-KEY.project-key=DOWNSTREAM-PROJECT-KEY
jira.project-group."your-project-group".projects.YOUR-SOURCE-PROJECT-KEY.original-project-key=UPSTREAM-PROJECT-KEY
jira.project-group."your-project-group".projects.YOUR-SOURCE-PROJECT-KEY.security.enabled=true
jira.project-group."your-project-group".projects.YOUR-SOURCE-PROJECT-KEY.security.secret=jira-webhook-secret
The tool takes the simple approach to mapping users, issue types, etc between Jira instances. Since all of these can differ between Jira instances, and then on top of that would be limited by the project scheme applied to a particular project, it is simpler for the tool just to ask the user to provide the direct mapping instead of guessing it. This section is here to provide some tips on how to get the info you need.
Use the jira/people/search
or rest/api/2/user/search?username=…
to find the users.
jira.project-group."your-project-group".users.mapping."source-user-id"=destination-user-id
Depending on the jira instance type you may also need to change
the property name that is used to specify the user in the downstream request.
By default, the tool will try to use the accountId
property, but for some Jira instances you may need to send
the user id/name/smth-else through a different property, e.g. name
. To do that add the following property:
jira.project-group."your-project-group".users.mapped-property-name=name
Review the project settings summary (e.g. https://your-jira-instance/plugins/servlet/project-config/your-project-key/summary
).
Use rest/api/2/priority
REST API to get the list of available priorities and pick the ones defined in the project scheme.
jira.project-group."your-project-group".priorities.mapping."source-id"=destination-id
You may also want to provide a default priority, to be used if mapped one is not available:
jira.project-group."your-project-group".priorities.default-value=3
Use the project REST API rest/api/2/project/{projectKeyOrId}
and inspect the issueTypes
array.
Alternatively, go to your project settings page and review the project settings summary (e.g. https://your-jira-instance/plugins/servlet/project-config/your-project-key/summary
).
Get the info from upstream/downstream projects and build a mapping in the application.properties
file as:
jira.project-group."your-project-group".issue-types.mapping."source-id"=destination-id
Issue status cannot be set directly through a REST API call. Instead, to change the issue status a transition has to be applied. That’s why upstream issue statuses are mapped to downstream transitions. To find the list of statuses review the result of ``
To find the list of transitions available for your project see, try /api/2/issue/{issueIdOrKey}/transitions
Note: only a single transition is going to be applied. Hence, make sure that the workflow allows to apply transitions from any state.
jira.project-group."your-project-group".statuses.mapping."source-status-id"=destination-transition-id
Use the project REST API rest/api/2/issueLinkType
and build the mappings.
Get the info from upstream/downstream projects and build a mapping in the application.properties
file as:
jira.project-group."your-project-group".issue-types.mapping."source-id"=destination-id
Note, creating sub-task is not supported by the tool, as there is no way of converting a task to a sub-task through REST at the moment. Hence instead a sub-task is created as a task, and an extra issue link is created for it of a type configured via a property:
jira.project-group."your-project-group".issue-link-types.parent-link-type=destination-id
Make sure the mapped users are added to the project
Assign the project users to the "viewer-only" role that does not have edit permissions to prevent accidental edits. Any updates/comments should be added to the upstream Jira tickets and synced through the tool.
Service account used by the tool for communication with the downstream Jira should be assigned to the project admin
role, so it could leverage the notifyUsers
query parameter where possible.
Disable email notifications for the project. Most likely you would need to request your Jira administrator to adjust the
notification scheme for the downstream project (see https://your-jira-instance/plugins/servlet/project-config/your-project-key/notifications).
If for some reason the notifications have to be kept enabled, consider adjusting the scheme so that notifications for
comments/issues/transitions updates do not include current assignee or reporter.
While the sync tool tries to leverage the notifyUsers
parameter to prevent emails
from being sent after the actions the tool perform, not all requests respect this parameter and emails may be sent out anyway.
Currently, the tool is deployed to an OpenShift. Deployment happens automatically when pushed to the production
branch.
See a corresponding GitHub action for details.
Add your OpenShift server url as a OPENSHIFT_SERVER_INFRA_PROD
GitHub secret.
See .github/workflows/deploy.yml.
Create a service account on OpenShift that will be used by the GitHub deploy action.
Note
|
With recent versions of OpenShift the token may not be automatically generated for the service account, if that’s so create one manually, e.g. create a token valid for a week: oc create token <serviceaccountname> --duration=$((7*24))h See also: |
Having the service account token ready, add it to the GitHub secretes as OPENSHIFT_TOKEN_INFRA_PROD
See .github/workflows/deploy.yml.
The OpenShift namespace needs to be added as a OPENSHIFT_NAMESPACE_INFRA_PROD
GitHub secrete.
See .github/workflows/deploy.yml.
Create and fill OpenShift Config maps and secrets.
These configs will depend on your application.properties
configuration
and what project groups were defined.
replicate-jira-config
Environment variables for the application.
Put in there whatever configuration you need for your specific cluster.
replicate-jira-secrets
Secret environment variables for the application.
Put in there whatever secret configuration you need for your specific cluster.
In particular, any REST API tokens, management passwords, Web Hook secrets.
There are management endpoints to sync particular issues/comments.
Note
|
TODO: Need to make sure that POST management endpoints actually work before describing all of them here… |
Currently, the app is set up to work with two test projects, JIRATEST1/JIRATEST2 at https://hibernate.atlassian.net/.
Create and add all necessary tokens to your local .env
file, e.g.:
JIRA_API_URL_HIBERNATE=https://hibernate.atlassian.net/rest/api/2 JIRA_API_USER_HIBERNATE=your-user JIRA_API_TOKEN_HIBERNATE=your-PAT JIRA_API_URL_REDHAT=https://hibernate.atlassian.net/rest/api/2 JIRA_API_USER_REDHAT=your-user JIRA_API_TOKEN_REDHAT=your-PAT
We also use https://smee.io/ to get web hooks delivered to the local env.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。