Config File

The config file is made up of multiple parts

'admins': ['demo_jira_username']

Admins can be users who manage Sync2Jira. They will be cc’d in any emails regarding duplicate issues found.

'mailing-list': 'demo_email@demo.com'

Mailing list is used to alert users when there is a failure. A failure email with the traceback will be sent to the email address.

'debug': False

Enable or disable debugging output. This will emit on fedmsg messages and can be very noisy; not for production use.

'testing': True

Testing is a flag that will determine if any changes are actually made downstream (on JIRA tickets). Set to false if you are developing and don’t want any changes to take effect.

'develop': False

If the develop flag is set to False then Sync2Jira will perform a sentinel query after getting a JIRA client and failure email will be sent anytime the service fails.

'github_token': 'YOUR_TOKEN',

This is where you can enter your GitHub API token.

'default_jira_instance': 'example'

This is the default JIRA instance to be used if none is provided in the project.

'jira': {
    'example': {
        'options': {
            'server': 'https://some_jira_server_somewhere.com',
            'verify': True,
        },
        'basic_auth': ('your-email@example.com', 'YOUR_API_TOKEN'),
    },
},

Here you can configure multiple JIRA instances if you have projects with differing downstream JIRA instances. Ensure to name them appropriately; in the example above the JIRA instance name is example.

You can choose the authentication method per instance with auth_method:

PAT (Personal Access Token) – default. Set auth_method: 'pat' and use basic_auth (email and API token, e.g. for Jira Cloud):

'example': {
    'options': {'server': 'https://jira.example.com', 'verify': True},
    'auth_method': 'pat',
    'basic_auth': (
          'email',
          'API Token'
        ),
},

OAuth 2.0 (2LO, service account) – Set auth_method: 'oauth2' and provide oauth2 with Atlassian client ID and secret (e.g. from a service account):

'example': {
    'options': {'server': 'https://your-domain.atlassian.net', 'verify': True},
    'auth_method': 'oauth2',
    'oauth2': {
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        # optional: 'token_url': 'https://auth.atlassian.com/oauth/token',
    },
},

If auth_method is omitted, PAT is assumed. To use OAuth 2.0, set auth_method to 'oauth2' and provide the oauth2 block.

"default_jira_fields": {
  "storypoints": "customfield_12310243"
},

The keys in the default_jira_fields map are used as the values of the github_project_fields list (see below). The keys indicate how the fields in GitHub Project items correspond to fields in Jira issues so that these values can be synced properly. Currently, we support only storypoints and priority. By default, the value for the priority is sourced from the upstream priority field, but providing a priority key for default_jira_fields will override that. Unfortunately, there is no default available for sourcing story points, so, the storypoints key must be provided if projects wish to sync story point values, and, for our corporate Jira instance, the value should be specified as customfield_12310243.

'map': {
        'github': {
            'GITHUB_USERNAME/Demo_project': {'project': 'FACTORY', 'component': 'gitbz',
                                            'issue_updates': [...], 'pr_updates': [...], 'mapping': [...], 'labels': [...],
                                            'owner': 'jira_username'},
        },
    },

You can add the following to your project configuration:
'project'

Downstream project to sync with

'component'

Downstream component to sync with

sync

This array contains information on what to sync from upstream repos (i.e. ‘issue’ and/or ‘pullrequest’)

'owner'

Optional (Recommended): Alerts the owner of an issue if there are duplicate issues present

'qa-contact'

Optional: Automatically add a QA contact field when issues are created

'epic-link'

Optional: Pass the downstream key to automatically create an epic-link when issues are created

'labels': ['tag1'..]

Optional: Field to have custom set labels on all downstream issues created.

'type'

Optional: Set the issue type that will be created. The default is Bug.

'issue_types': {'bug': 'Bug', 'enhancement': 'Story'}

Optional: Set the issue type based on GitHub labels. If none match, fall back to what type is set to.
- 'EXD-Service': {'guild': 'SOME_GUILD', 'value': 'SOME_VALUE'}
  
  Sync custom EXD-Service field
  Note
  
  pullrequest:
  
  After enabling PR syncing, just type “JIRA: XXXX-1234” in the comment or description of the PR to sync with a JIRA issue. After this, updates such as when it has been merged will automatically be added to the JIRA ticket.
You can add your projects here. The 'project' field is associated with downstream JIRA projects, and 'component' with downstream components. You can add the following to the issue_updates array:
- 'comments'
  
  Sync comments and comment edits
- {'tags': {'overwrite': True/False}}
  
  Sync tags, do/don’t overwrite downstream tags
- {'fixVersion': {'overwrite': True/False}}
  
  Sync fixVersion (downstream milestone), do/don’t overwrite downstream fixVersion
- {'assignee': {'overwrite': True/False}}
  
  Sync assignee (for Github only the first assignee will sync) do/don’t overwrite downstream assignee
  
  Note that the downstream assignee is selected by performing an LDAP query for the upstream user in the “Professional Social Media” link in the RoverPeople profiles, so, in order for this feature to work properly, each potential assignee needs to ensure that they have added their upstream identity(es) to their Rover profile.
- 'description'
  
  Sync description
- 'title'
  
  Sync title
- {'transition': 'CUSTOM_TRANSITION', 'issue_types': ['Bug', 'Story']}
  
  Sync status (open/closed). Attempt to transition JIRA ticket to CUSTOM_TRANSITION on upstream closure.
  
  issue_types is optional and may be omitted. When present, the transition only fires if the downstream JIRA issue type is in the list.
- {'on_close': {'apply_labels': ['label', ...]}}
  
  When the upstream issue is closed, apply additional labels on the corresponding Jira ticket.
- github_markdown
  
  If description syncing is turned on, this flag will convert Github markdown to Jira syntax. This uses the pypandoc module.
- upstream_id
  
  If selected this will add a comment to all newly created JIRA issue in the format ‘UPSTREAM_PROJECT-#1’ where the number indicates the issue ID. This allows users to search for the issue on JIRA via the issue number.
- url
  
  This flag will add the upstream url to the bottom of the JIRA ticket
- github_project_number
  
  Specify the GitHub project number. If specified, story points and priority will be selected from this project, and other projects linked to the issues will be ignored.
- github_project_fields
  
  Sync GitHub projects fields. e.g, storypoints, priority
Note

Overwrite:

Setting this to True will ensure that Upstream (GitHub) values will overwrite downstream ones (i.e. if its empty upstream it’ll be empty downstream)

CUSTOM_TRANSITION:

Setting this value will get Sync2Jira to automatically transition downstream tickets once their upstream counterparts get closed. Set this to whatever ‘closed’ means downstream.
You can add your projects here. The ‘project’ field is associated with downstream JIRA projects, and ‘component’ with downstream components. You can add the following to the pr_updates array:
- {'merge_transition': 'CUSTOM_TRANSITION', 'branches': ['release-*', 'main'], 'issue_types': ['Bug', 'Story']}
  
  Sync when upstream PR gets merged. Attempts to transition JIRA ticket to CUSTOM_TRANSITION on upstream merge.
  
  branches and issue_types are optional and either may be omitted. branches accepts glob patterns and restricts the transition to PRs whose target branch matches. issue_types restricts it to matching downstream JIRA issue types.
- {'link_transition': 'CUSTOM_TRANSITION'}
  
  Sync when upstream PR gets linked. Attempts to transition JIRA ticket to CUSTOM_TRANSITION on upstream link.
You can add the following to the mapping array. This array will map an upstream field to the downstream counterpart using either a template or a mapping table.
- {'fixVersion': 'Test XXX'}
  
  String template format. Maps upstream milestone (suppose it’s called ‘milestone’) to downstream fixVersion with a mapping (for our example it would be ‘Test milestone’).
- {'fixVersion': {'0.9.0': 'Product 8.1', '1.0.0': 'Product 9.0'}}
  
  Dict lookup format. Maps specific upstream milestones to specific downstream fixVersions. Milestones not present in the dict are left unchanged.
It is strongly encouraged for teams to use the owner field. If configured, owners will be alerted if Sync2Jira finds duplicate downstream issues. Further the owner will be used as a default in case the program is unable to find a valid assignee.

'github_project_fields': {
    'storypoints': {
      'gh_field': 'Estimate'
    },
    'priority': {
      'gh_field': 'Priority',
      'options': {
        'P0': 'Blocker',
        'P1': 'Critical',
        'P2': 'Major',
        'P3': 'Minor',
        'P4': 'Optional',
        'P5': 'Trivial'
      }
    }
}

Specify the GitHub project field and its mapping to Jira. The currently supported fields are storypoints and priority.
The gh_field points to the GitHub field name.
The options key is used to specify a mapping between GitHub field values as Jira field values. This is particularly useful for cases like priority which uses keywords for values.

'filters': {
        'github': {
            # Only sync multi-type tickets from bodhi.
            'fedora-infra/bodhi': {'status': 'open', 'milestone': 4, },
        },
    }

You can also add filters per-project. The following can be added to the filter dict:
- status
  
  Open/Closed
- tags
  
  List of tags to look for
- milestone
  
  Upstream milestone status