Clazzes.org pytools Jira Client ======================= A Command Line Interface for requests to Jira API. Supports reading from and writing issues to projects as well as creation of OAuth 1.0a Tokens. Supports both Basic and OAuth Authentication and usage of config files. ==================================== ------------- COMMANDS ------------- ==================================== When executing a command, all required parameters for the operation will be checked for existence. If one or more are missing, an error will appear listing the missing parameters. When using parameters, precedence is taken for command-line supplied ones over config-file supplied ones. When submitting a string with one or more whitespace characters in between(common when submitting a description for a new issue, for example), that string must be surrounded by ' or " on the command line. See usage examples below. Use 'jira-client -h' for in-terminal help. listissues ^^^^^^^^^ Pretty prints, to stdout, all the issues for a given project name, in order of creation descending. Could redirect output to save in file. Required parameters(postional): 1) The project's identifier in Jira Optional parameters: None Required Jira Permissions: Issue Browsing createissue ^^^^^^^^^^^ Required parameters: --project: The identifier of the project to add the issue to. --summary: Headline of the issue to be created. Put in quotation marks if it contains spaces. --desc: Description of the issue to be created. If a single hyphen('-') is specified, then read the standard input to JiraClient(usually piped) and use that. --issuetype: How the issue should be categorized. Examples are bug, task, feature, subtask,... --priority: Number from 1-5 where 1 is a Blocker and 5 is Trivial. Optional parameters: --assignee: The username of the requested assignee, if one should be immediately assigned. --parent: The identifier of the parent issue. Only required if you create a subtask. Required Jira Permissions: Issue Browsing, Issue Creation initconfig ^^^^^^^^^^ Required parameters: None Optional parameters: --conffile: Absolute path to the file where the config values should be saved/overwritten. If it doesn't exist, attempt to create it there. -> Any of --username, --password, --oAuthToken, --consumerKey, --consumerSecret, --oAuthSecretToken, --authMethod, --privateKeyLocation, --baseurl that should be saved in the config file Required Jira Permissions: None createoauth ^^^^^^^^^^^ Required parameters: --consumerkey: The name of the OAuth public key as configured on the Jira Server. Specify to use a different one than the config file has. --consumersecret: The OAuth secret as configured on the Jira Server. Specify to use a different one than the config file has. --pkeyloc(command line)/privatekeylocation(config key): Path to the private to be used for the creation of this token. Optional parameters: None Required Jira Permissions: None; OAuth Consumer must have been configured server-side by an Administrator. A Tutorial on how to configure that can be found on the official Atlassian Jira Documentation: https://developer.atlassian.com/server/jira/platform/oauth/ (Only Step 1 is relevant, Step 2 and 3 are handled by JiraClient) ==================================== ----------- CONFIG FILES ----------- ==================================== By default, the CLI checks for existence of config files both in the user folder(~/.jiraclient/jiraclient.conf) and the global /etc folder(/etc/jiraclient/jiraclient.conf) to read from. When both exist, the user config takes precedence. Alternatively, when a config path is specified via the --config/-c option, that one takes precedence over both user and global config. Config files can be automatically initialized using the initconfig helper command, or created with the following structure: [CLI] = = . . . = Parameter keys that are recognized when reading a config file are: -> baseurl -- The Jira URL to connect to. "Base" means up to and including the domain, without any subpages, and including the slash at the end. -> username -- Needed when using BasicAuth authentication. -> password -- Needed when using BasicAuth authentication. -> oauthtoken -- Needed when using OAuth authentication. Can be enrolled with the createoauth command, given sufficient permissions. -> oauthsecrettoken -- Needed when using OAuth authentication. Usually delivered right along the regular OAuth Token. -> auth -- The authentication method used. Only valid values are "BASICAUTH" and "OAUTH". -> consumerkey -- The identifier of the Public Key corresponding to the Private Key used to sign OAuth messages. Can be configured on Jira. Case sensitive. -> consumersecret -- The value of the shared secret used within OAuth authentication. Can be configured on Jira. -> privatekeylocation -- An absolute filepath to the private key used to sign OAuth requests. Must correspond to the public key configured on the Jira server. Note that the corresponding option to the privatekeylocation config is --pkeyloc. Example config file: [CLI] baseurl = https://jira.example.com/ auth = OAUTH username = johndoe password = 49sTo5*MFF2 oauthtoken = jPoXwIyWlLpcMELqIpKvMnPlrKqztp28 oauthsecrettoken = uAtfg9eSeMWG0JsNZZcastAWfnwUnoNL consumerkey = jiraKeyOauth consumersecret = hs0238fkla privatekeylocation = /home/johndoe/.gnupg/jirakey.pem ==================================== ----------- EXAMPLE USAGE ---------- ==================================== listissues ^^^^^^^^^^ List issues for project with "id" attribute EXAMPLEPROJECTNAME """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" jira-client listissues EXAMPLEPROJECTNAME """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Example Output: """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" EXAMPLEPROJECTNAME-2 (Bug): Priority 3 - Heavy DB leaks lead to security invulnerabilities Created by John Doe at Thu, 14.06.2012 17:39:21 (UTC+02:00) Assigned to Will Dugh Last updated: Tue, 13.11.2012 17:26:06 (UTC+01:00) ---------------------------- EXAMPLEPROJECTNAME-1 (Feature): Priority 4 - Minor Should allow filtering of currently online users Created by Will Dugh at Wed, 14.06.2012 17:39:21 (UTC+02:00) Assigned to Nobody Last updated: Never ---------------------------- """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" initconfig ^^^^^^^^^^ 1.) Initialize the user config file from scratch interactively: """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" > jira-client initconfig Enter config file path (Alternatively enter 'u' for user or 'g' for global config): > u Enter remaining configurable values, leave empty to ignore: username: > johndoe password: > notapassword123 oAuthToken: consumerKey: > notakey987 consumerSecret: authMethod: > OAUTH privateKeyLocation: > /home/johndoe/mykeyring/pkey.pem baseurl: > https://jira.mydomain.com """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" This will set username, password, consumerKey, authMethod, privateKeyLocation and baseurl to the specified values and leave the rest alone. 2.) Initialize a config file to a custom path with all parameters already set: """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" > jira-client initconfig --conffile /home/johndoe/customjira.conf --username johndoe --password notapw123 --oauthtoken Jb72NuBYBvT9zfrYfXCzdfF7y11X6ewC --oauthsecrettoken lxpMs8QIllXE3Y9kxGu3yakyyqHs5kh3 --auth OAUTH --consumersecret notasecret1923 --consumerkey notakey29 --pkeyloc /home/johndoe/mykeyring/pkey.pem --baseurl https://jira.mydomain.com """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" No output if successful. createissue ^^^^^^^^^^^ 1.) Create an issue for EXAMPLEHOSTINGNAME project which is a Bug with Priority Minor(4): """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" jira-client createissue --project EXAMPLEPROJECTNAME --summary "This is the headline" --desc "This is a multi-lined\ndescription" --issuetype Bug --priority 4 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" No output if successful. 2.) Create an issue with the content of a file(possibly an email) as its description. """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" jira-client createissue --project EXAMPLEPROJECTNAME --summary "This is the headline" --issuetype Bug --priority 4 < test-description.txt """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" createoauth ^^^^^^^^^^^ Can only be done interactively because OAuth1.0a requires manual user authentication. Creating the OAuthToken and saving it to user config file: """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" > jira-client createoauth Request token recieved, please authorize me in the Browser via the following URL: https://jira.mydomain.com/plugins/servlet/oauth/authorize?oauth_token=60uUqPdN237z3qjOCafLeNWHJHO2g6zw Have you authorized me? (Y/n) >>> (Manual authentication in browser) >>> > Y {'oauth_token': 'yPpXwNyWeLpc923qIpKvMLCabVqztb28', 'oauth_token_secret': 'uDtPg6ePeKWG9JsNZZblubAWfnwbCoNl', 'oauth_expires_in': '157680000', 'oauth_session_handle': 'bmF8KVnnF2AMwUX6AAZ8P5Oc3WtS0b5A', 'oauth_authorization_expires_in': '160272000'} Save OAuth Token to user or global config, or none (u/g/n)? Alternatively, enter a custom absolute file path(starting with /): > u """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""