This GitHub Action will query Jira using JQL provided as an input, and will transition any issues it finds to a given status.
If the Jira server is hosted on an internal network, then the action must run on a runner that has access to that network.
Work items, tickets, etc. are referenced as "issues" in this action.
| Parameter | Is Required | Description |
|---|---|---|
domain-name |
true | The domain name for Jira. |
jql-query |
conditionally* | The JQL query to use to find issues that will be transitioned. A max of 20 issues can be transitioned. |
issues |
conditionally* | Comma delimited list of issues to transition. Use im-open/get-workitems-action to identify list of issues for a PR or deployment. |
transition-name |
true | The name of the transition to perform. Examples might include Open, In Progress, Deployed, etc. |
update-fields |
false | A map of issue screen fields to overwrite, specifying the sub-field to update and its static value(s) for each field. When multiple sub-fields or other operations are required, use 'process-operations' input instead. |
process-operations |
false | A map containing the field name and a list of operations to perform. The fields included in here cannot be included in 'update-fields' input. |
comment |
false | Add a comment to the issue after the transition. |
missing-transition-as-successful |
false | Mark as a successful if issue is missing the transition. true by default. |
create-notice |
false | Add notification to runner with details about successful transitioned issues. true by default. |
create-warnings |
false | Add warning notifications to runner. true by default. |
fail-on-transition-failure |
false | Fail if some issues failed transitioning. true by default. |
fail-if-issue-excluded |
false | Fail if some issues are excluded that are listed in the issues input but not identified by query. true by default. |
fail-if-jira-inaccessible |
false | Fail if Jira is inaccessible at the moment. Sometimes Jira is down but shouldn't block the pipeline. false by default. |
jira-username |
false | The username to login to Jira with in order to perform the transition. |
jira-password |
false | The password to login to Jira with in order to perform the transition. |
* Either
jql-queryorissuesinput is required. If both are provider, both will be included.
| Output | Description | Type |
|---|---|---|
processed-issues |
Issues successfully transitioned, skipped and (if enabled) with an unavailable transition. | Comma-delimited list |
transitioned-issues |
Issues successfully transitioned. | Comma-delimited list |
failed-issues |
Issues in Jira not successfully processed. | Comma-delimited list |
unavailable-issues |
Issues missing the specified transition. | Comma-delimited list |
excluded-issues |
Issues excluded that are listed in the issues input but not identified by query. |
Comma-delimited list |
is-successful |
One or more issues were transitioned successfully and/or skipped. If missing-transition-as-successful enabled, also includes missing transitions. |
Boolean |
some-identified |
Some issues were found in Jira. | Boolean |
some-transitioned |
Some issues were transitioned successfully. | Boolean |
some-unavailable |
Some issues do not have transition. | Boolean |
some-skipped |
Some issues skipped when already transitioned or other causes. | Boolean |
some-excluded |
Some issues were excluded. | Boolean |
jobs:
transition-jira-issue:
runs-on: ubuntu-20.04
steps:
- name: Get work items
uses: im-open/get-work-items-action@latest
id: get-issues
with:
create-env-variable: true
reference: v1.2.3
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Transition Jira Issue to Deployed Status
# You may also reference just the major or major.minor version
uses: im-open/[email protected]
id: transition
with:
jira-username: ${{ vars.JIRA_USERNAME }}
jira-password: ${{ secrets.JIRA_PASSWORD }}
domain-name: jira.com
transition-name: Deployed
issues: ${{ steps.get-issues.outputs.result-list }}
# jql-query: 'issuekey=PROJ-12345'
# jql-query: "filter='My Filter Name' AND issuekey=PROJ-12345"
# jql-query: 'component IN ("System Infrastructure') AND "Deployment Version" ~ 'v1.2.1''
# issues: TW-1234, TW-4455
# issues: |
# TW-1234
# TW-4455
# etc.
# If you want to update or overwrite fields, you can use the following inputs:
# update-fields: |
# {
# "customfield_12345": "some value"
# }
# Some issue types don't have a transition status like others.
# In those cases, where you want to still transition, a second step will need to be invoked.
# You can pass in the `unavailable-issues` output to transition those remaining issues.
- name: Transition Remaining Jira issues to Closed Status
uses: im-open/[email protected]
with:
jira-username: ${{ vars.JIRA_USERNAME }}
jira-password: ${{ secrets.JIRA_PASSWORD }}
domain-name: jira.com
transition-name: Closed
issues: ${{ steps.transition.outputs.unavailable-issues }}They are two different ways to update fields. Passing a update-fields input or an process-operations input. You may not specify the same field name in both the update-fields and process-operations inputs.
If you are unsure what field names to use, run the Get-Jira-Issue script locally.
You may also use the field's display name
Related:
- Custom Fields
- Atlassian Edit Issues Example for additional help
The easiest solution is to pass update-fields input with static changes. These must be screen fields -- fields that a user can edit in Jira on the specific issue type. If the field doesn't exist on the issue type, it will be ignored.
The update-fields input would be something like:
{
"assignee": {
"name": "bob"
},
"resolution": {
"name": "Fixed"
},
"customfield_40000": {
"value": "red"
}
}If a field doesn't exist on a given Issue Type, it will be ignored
Update fields by operation(s). Adding multiple components, creating a link to another issue, adding additional values to a multi-select field, etc. Updating operations allows you to add or remove additional values to fields without overwriting what is already there.
The process-operations fields would be something like:
{
"components" : [
{
"remove" : {
"name" : "Trans/A"
}
},
{
"add" : {
"name" : "Trans/M"
}
}
]
}If an operation doesn't exist on a given Issue Type, it will be ignored
When creating PRs, please review the following guidelines:
- The action code does not contain sensitive information.
- At least one of the commit messages contains the appropriate
+semver:keywords listed under Incrementing the Version for major and minor increments. - The README.md has been updated with the latest version of the action. See Updating the README.md for details.
This repo uses git-version-lite in its workflows to examine commit messages to determine whether to perform a major, minor or patch increment on merge if source code changes have been made. The following table provides the fragment that should be included in a commit message to active different increment strategies.
| Increment Type | Commit Message Fragment |
|---|---|
| major | +semver:breaking |
| major | +semver:major |
| minor | +semver:feature |
| minor | +semver:minor |
| patch | default increment type, no comment needed |
The files and directories that are considered source code are listed in the files-with-code and dirs-with-code arguments in both the build-and-review-pr and increment-version-on-merge workflows.
If a PR contains source code changes, the README.md should be updated with the latest action version. The build-and-review-pr workflow will ensure these steps are performed when they are required. The workflow will provide instructions for completing these steps if the PR Author does not initially complete them.
If a PR consists solely of non-source code changes like changes to the README.md or workflows under ./.github/workflows, version updates do not need to be performed.
If changes are made to the action's source code, the usage examples section of this file should be updated with the next version of the action. Each instance of this action should be updated. This helps users know what the latest tag is without having to navigate to the Tags page of the repository. See Incrementing the Version for details on how to determine what the next version will be or consult the first workflow run for the PR which will also calculate the next version.
This project has adopted the im-open's Code of Conduct.
Copyright © 2023, Extend Health, LLC. Code released under the MIT license.