Get work items

Parses out work items from PR or release title, description and its related commits.

Prioritization

Prioritizes work items by:

1. PR title & description
2. Or Release name & Release body
3. Commits descending

Pattern

Within the PR title, identifies one work item.

ABC-1234: My Title

Within the description of the PR, identifies multiple work items.

Resolved

Work items can be filtered even more by specific keyword prefixes.

If a work item exists in the title of the PR or the name of a release, it is considered resolved by default.

For work items listed in the PR description, release description or in commits, by default they are not marked as resolved. You may mark work items as resolved by adding one of the keyword prefixes (similar to closing a GitHub Issue):

• close
• closes
• closed
• fix
• fixes
• fixed
• resolve
• resolves
• resolved

resolves TW-1234

Index

• Inputs
• Outputs
• Usage Examples
• Contributing
  • Recompiling
  • Incrementing the Version
• Code of Conduct
• License

Inputs

Parameter	Is Required	Default	Description
context	false		Identify work items in context input instead of the current PR or release context.
patterns	false	\b[a-zA-Z]+-\d+\b	Expressions used in identifying work items. ie. EN-1234
list-delimiter	false	,	Separate work items with this delimiter.
include-commits	false	false	Include searching for work items in commits found within the PR or release. Pulls up to 100 commits. If a branch, tag or sha is used instead, will look within commits even if this variable is set to false.
reference	false		Release, tag, branch or sha to search for work items. You can also pass the fully-formed ref from github.ref context. If not used, defaults to the current workflows context.
fallback-to-workflow-context	false	false	If reference is empty, fallback to workflow's context.
github-token	false		If context is not provided, the GitHub token for interacting with the repository and gather PR contexts.
create-env-variables	false	false	Create environment variables with output.
only-resolved	false	true	Identify work items that are prefixed with a resolve keyword.
target-url-pattern	false		URL pattern using a token {item} to construct a link to the work items. https://work-items.com/{item}
create-notice	false	true	Add notification to runner with details.
create-warnings	false	true	Add warning notifications to runner.
fail-on-missing-except-for-labels	false	non-production	When fail-on-missing enabled, ignore when one of these labels are present on the PR.
fail-on-missing	false	false	Fail if no work items are found.
fail-on-error	false	true	Fail on missing context.

If you plan on including commits or a release, you must pass the secret.GITHUB_TOKEN into the action

Outputs

Output	Description
found	true or false if work items were found.
count	Number of work items found.
primary	Highest prioritized work item.
primary-link	Highest prioritized work item wrapped in Markdown link.
result	JSON array of all work items ordered by priority.
result-list	Comma delimited list of items ordered by priority.
result-markdown-list	Markdown list of all work items ordered by priority.
result-markdown-links	Markdown comma delimited list of all work items ordered by priority with links.
result-markdown-list-links	Markdown list of all work items ordered by priority with links.

Usage Examples

jobs:
  jobname:
    runs-on: ubuntu-latest
    steps:
      - name: Get work items from PR
        uses: im-open/get-work-items-action@v4
        with:
          # Don't have to include anything else unless you plan on including commits
          # If you plan on including commits or a release, you must pass the secret.GITHUB_TOKEN into the action
          create-env-variables: true
          target-url-pattern: https://work-items.com/{item}

        # PR has a title: 'ABC-1234: PR Title Example'
        # PR has a description: 'Resolved ABC-2222 but still working on ABC-8888'

        # Step variables
        env.PRIMARY_WORK_ITEM = ABC-1234
        env.PRIMARY_WORK_ITEM_LINK = [ABC-1234](https://work-items.com/ABC-12324)
        env.WORK_ITEM_RESULT = ["ABC-1234", "ABC-2222"]
        env.WORK_ITEM_RESULT_LIST = ABC-1234, ABC-2222
        env.WORK_ITEM_RESULT_MARKDOWN_LIST = - ABC-1234\n- ABC-2222
        env.WORK_ITEM_RESULT_MARKDOWN_LINKS = [ABC-1234](https://work-items.com/ABC-1234), [ABC-2222](https://work-items.com/ABC-2222)
        env.WORK_ITEM_RESULT_MARKDOWN_LIST_LINKS = - [ABC-1234](https://work-items.com/ABC-1234)\n- [ABC-2222](https://work-items.com/ABC-2222)
        env.WORK_ITEMS_FOUND = true
        env.WORK_ITEMS_COUNT = 2

        outputs.primary = ABC-1234
        outputs.result = ["ABC-1234", "ABC-2222"]
        # Notice the order and ABC-8888 was not identified

        # The result output can also be a delimited list instead of a serialized JSON array.
        # Convenient when adding work items to a release description

      - name: Comment on PR with work items ${{ env.PRIMARY_WORK_ITEM }}
        if: github.event_name == 'pull_request' && env.WORK_ITEMS_FOUND == 'true'
        uses: im-open/update-pr-comment@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          comment-identifier: work-items
          comment-content: |
            Work items identified in PR: ${{ env.WORK_ITEM_RESULT_LIST }}

See workflow automated test for more examples

Contributing

When creating new PRs please ensure:

1. The action has been recompiled. See the Recompiling section below for more details.
2. For major or minor changes, at least one of the commit messages contains the appropriate +semver: keywords listed under Incrementing the Version.
3. The README.md example has been updated with the new version. See Incrementing the Version.
4. The action code does not contain sensitive information.

Recompiling

If changes are made to the action's code in this repository, or its dependencies, you will need to re-compile the action.

# Installs dependencies and bundles the code
npm start

# Bundle the code (if dependencies are already installed)
npm run build

These commands utilize esbuild to bundle the action and its dependencies into a single file located in the dist folder.

Incrementing the Version

This action uses git-version-lite to examine commit messages to determine whether to perform a major, minor or patch increment on merge. 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

Code of Conduct

This project has adopted the im-open's Code of Conduct.

License

Copyright © 2022, Extend Health, LLC. Code released under the MIT license.