jira-api-issue-resource

_{Some section needs to be updated}

Version: 1.4.3

Build status	Scrutinizer

_{Project certification on default branch (master)}

This Concourse resource allows a pipeline to interface with a Jira REST API in order to manage (create/update/delete) issues. It is intended to be as dynamic and generic as possible to allow a vast array of possible uses. In this regard it is important to know that jira-api-issue-resource benefits greatly from being used with glif.

For a more complete example of a pipeline configured with both this resource and glif see the 'example' folder.

Table of content

Resource Type Configuration
Source Configuration
Behavior
1. Check
2. In
3. Out
Contributing

Resource Type Configuration

resource_types:
    - name: jira-api-issue
      type: docker-image
      source:
          repository: turnscoffeeintoscripts/jira-api-issue-resource
          tag: latest

Source Configuration

resources:
    - name: jira
      type: jira-api-issue
      source:
          url: https://...
          username: XXXX
          password: ((password-in-vault)
          context: <SEE_CONTEXT_USAGE>

Firstly, here's a list of all required and optionnal parameters followed by a list of the optionnal flags:

Required Parameters Definition

Parameter	Default Value	Description
`url`	nil	The base URL of the Jira API
`user`	nil	The username used to connect to the Jira API
`password`	nil	The password needed to connect to the Jira API
`context`	nil	The context of execution (see 'Context Usage bellow')

Optionnal Parameters Definition

Parameter	Default Value	Description
`loggingLevel`	`INFO`
`transitionName`	`Reopened`
`closedStatusName`	`Closed`

Optionnal Flags Definition

Flag	Description
`forceOnParent`
`forceOpen`

Context Usage

Here's the list of the available contexts that can be used. Each context will directly influence what operations will be performed by the resource.

ReadIssue
ReadStatus
EditCustomField
AddComment

ReadIssue

Documentation coming soon...

ReadStatus

Documentation coming soon...

EditCustomField

This context allows the resource to be used in 'put' steps. It also allows the edition of any free text element in a Jira issue. These elements are referred to as 'custom fields'.

Here's a simple example of the resource's configuration:

resources:
  - name: jira-build-number
    type: jira-api-issue
    source:
      url: https://jira....
      username: username1
      password: ((password-in-vault))
      context: EditCustomField
      custom_field_name: "Build Number"
      custom_field_type: "string"

As can be seen in this configuration neither the field value or the issue(s) are specified. Since this resource is meant to be as dynamic as possible those values will be provided in the put step. The first example is done without the use of glif. Therefore the issue(s) are directly specified in the parameters. The parameter custom_field_value is also used meaning the value that will be put in the issue(s) is hardcoded in the put step configuration.

jobs:
  - name: add-build-number
    serial: true
    public: false
    plan:
      ...
      - put: jira-build-number
        params:
          issues: "ABC-123 XYZ-1649 TEST-456"
          custom_field_value: "1.0.0"

Next is a more dynamic (and realistic) example. Glif is used meaning we have a dynamic list of issues. The custom value is also specified via a file that a previous step will provide; perfect if you're using the semver concourse resource.

jobs:
  - name: add-build-number
    serial: true
    public: false
    plan:
      ...
      - get: version-rc # semver resource
      - task: glif
        file: path/to/glif/task/file.yml
      - put: jira-build-number
        params:
          issue_file_location: path/to/directory/
          custom_field_value_from_file: path/to/file/with/value.txt

_{You may want to read glif documentation to properly
setup the glif task in this example}

Lets explain the two paramters issue_file_location and custom_field_value_from_file.

The first parameter, issue_file_location, is the path to the directory in which there is one or more file (*.txt) containing the list of issues.
The second parameter, custom_field_value_from_file, is the path to the file containing the value to edit in said issue(s).

AddComment

This context allows the resource to be used in 'put' steps. It simply adds a comment to the specified issue(s).

Here's a simple example of the resource's configuration:

resources:
  - name: jira-comment
    type: jira-api-issue
    source:
      url: https://jira....
      username: username1
      password: ((password-in-vault))
      context: AddComment

The actual body of the comment (the text) is set in the 'params' section of the step:

jobs:
  - name: put-jira-comment
    serial: true
    public: false
    plan:
      ...
      - put: jira-comment
        params:
          issues: "ABC-123 XYZ-1649 TEST-456"
          comment_body: "Comment made from Concourse"

This step will post a the comment Comment made from Concourse to each of the following issues: ABC-123, XYZ-1649 and TEST-456.

Behavior

Check

NOOP: does nothing.

In

NOOP: does nothing. There are feature that will be coming soon.

Out

Edit the issue(s) specified in the step parameters. Depending on the context defined in the resource various fields or parameters will be updated. For more specific see the context usage section.

Contributing

Anybody is welcome to contribute to this resource. You should checkout the master branch and create your feature branch from there. Only pull-requests made to the master branch will be looked at and eventually accepted. Once master is stable and contains the desired feature a release (tag, docker image) will be made.

For any questions or inquiries you can send an email at: [email protected]

turnscoffeeintoscripts / jira-api-issue-resource Goto Github PK