issue-sync

Issue-sync is a tool for mirroring GitHub issues in JIRA. It grew out of a desire to maintain a public GitHub repo while tracking private issues in a JIRA board; rather than require people to keep up with both sources, we decided to make one the single source of truth. Note that issue-sync works only one way and will NOT mirror issues from JIRA to GitHub.

Usage

JIRA Configuration

To use, first ensure you have a JIRA server with the project you want to track on it - it can be a cloud account, or self-hosted. Also make sure you have a user account that can access the project and create issues on it; it's recommended that you create an account specifically for the issue-sync tool.

Add the following custom fields to the project: GitHub ID, GitHub Number, GitHub Labels, GitHub Status, GitHub Reporter, and Last Issue-Sync Update. These fields are required and the names must match exactly. In addition, GitHub ID and GitHub Number must be number fields, Last Issue-Sync Update must be a date time field, and the remainder must be text fields.

If you intend to use OAuth with JIRA, you must create an inbound application connection and add a public key. Instructions can be found in OAuth for Rest APIs.

Application Configuration

Arguments to the program may be passed on the command line or in a JSON configuration file. For the command line arguments, run issue-sync help. The JSON format is a single, flat object, with the argument long names as keys.

Configuration arguments are as follows:

Configuration Key Descriptions

log-level is the minimum level which will be logged; any output below this value will be discarded.

github-token is a personal access token used to access GitHub as a specific user.

jira-user and jira-pass are the username (i.e. email) and password of the JIRA user which will be authenticated. See Authentication for more details.

jira-token and jira-secret are OAuth access tokens which will be used to perform an OAuth connection to JIRA. jira-consumer-key and jira-private-key-path are the RSA key used for OAuth. See Authentication for more details.

repo-name is the GitHub repo from which issues will be retrieved. It must be in the form owner/repo, for example coreos/issue-sync.

jira-uri is the base URL of the JIRA instance. If the JIRA instance lives at a non-root URL, the path must be included. For example, https://example.com/jira.

jira-project is the key (not the name) of the project in JIRA to which the issues will be synchronized.

since is the cutoff date issue-sync will use when searching for issues to synchronize. If an issue was last updated before this time, it will not be synchronized. Usually this is the last run of the tool. It is in ISO-8601 format.

timeout represents the duration of time for which an API request will be retried in case of failure. Human-friendly strings such as 30s are accepted as input, although the application will save it to the file in a number of nanoseconds.

Configuration File

By default, issue-sync looks for the configuration file at $HOME/.issue-sync.json. To override this location, use the --config option on the command line.

If both a configuration file and command line arguments are provided, the command line arguments override the configuration file.

After a successful run, the current configuration, with command line arguments overwritten, is saved to the configuration file (either the one provided, or $HOME/.issue-sync.json); the "since" date is updated to the current date when the tool is run, as well.

Authentication

If jira-user or jira-pass are provided, both are required, and the application will connect to JIRA via Basic Authentication.

Otherwise, OAuth will be used. In this case, the jira-consumer-key, which is the name of the RSA public key on the JIRA server, and the jira-private-key, which is the path to the RSA private key which matches, must be provided.

If the jira-token and jira-secret are provided, they are used as the OAuth access token.

If they are not provided, an OAuth handshake occurs, and an authorization URL will be given. The user will need to open the URL in their browser, and receive the authorization code provided. Once the code is entered into the application, an access token will be generated, and it will be added to the configuration for future use.