GitHub Actions powered Issue Bot ๐ฆพ
Work on a distributed team? Try using Issue Bot as a Scrum standup process automation bot to keep track of what you're all working on. ๐ค
Have repeated tasks you're setting reminders for elsewhere? Issue Bot's got your back there, too. ๐
Or just need an issue created on a certain condition? Issue Bot is there when your CI build breaks. ๐
Issue Bot is a flexible GitHub action that takes care of a few issue related tasks:
- Opens new issue with
title
,body
,labels
, andassignees
- Uses Mustache templating syntax in
body
, along with a couple of handy template variables:assignees
andpreviousIssueNumber
- Closes most recent previous issue with all
labels
ifclose-previous
is true - Adds new issue to
project
(user, organization, or repository project based on value ofproject-type
),column
, andmilestone
- Adds new issue to user or organization project at
project-v2-path
- Pins new issue and unpins previous issue if
pinned
is true - Makes issue comments linking new and previous issues if
linked-comments
is true - Assigns new issue only to the next assignee in the list if
rotate-assignees
is true. Useful for duty rotation like first responder. - Pairs well with imjohnbo/extract-issue-template-fields if you'd prefer to open issues based on issue templates
v2
user, please note that these breaking changes were introduced in v3
:
template
functionality has been moved to a separate action: https://github.com/imjohnbo/extract-issue-template-fields.labels
now checks if all labels match. Before, it checked if any labels matched.
and these features were added ๐:
project
andcolumn
for adding an issue to a repository project board.milestone
for adding an issue to a milestone.
As always, your feedback and contributions are welcome.
Simple example:
# ...
- name: Create new issue
uses: imjohnbo/issue-bot@v3
with:
assignees: "octocat, monalisa"
title: Hello, world
body: |-
:wave: Hi, {{#each assignees}}@{{this}}{{#unless @last}}, {{/unless}}{{/each}}!
pinned: true
# ...
For more examples, see a GitHub-wide search or ./docs/example-workflows:
See action.yml for full description of inputs and outputs.
Generated by imjohnbo/action-to-mermaid
:
flowchart LR
token:::optional-->action(Issue Bot Action):::action
title:::required-->action(Issue Bot Action):::action
body:::optional-->action(Issue Bot Action):::action
labels:::optional-->action(Issue Bot Action):::action
assignees:::optional-->action(Issue Bot Action):::action
project-type:::optional-->action(Issue Bot Action):::action
project:::optional-->action(Issue Bot Action):::action
column:::optional-->action(Issue Bot Action):::action
milestone:::optional-->action(Issue Bot Action):::action
pinned:::optional-->action(Issue Bot Action):::action
close-previous:::optional-->action(Issue Bot Action):::action
linked-comments:::optional-->action(Issue Bot Action):::action
linked-comments-new-issue-text:::optional-->action(Issue Bot Action):::action
linked-comments-previous-issue-text:::optional-->action(Issue Bot Action):::action
rotate-assignees:::optional-->action(Issue Bot Action):::action
action(Issue Bot Action)-->issue-number:::output
action(Issue Bot Action)-->previous-issue-number:::output
action(Issue Bot Action)-->project-v2-issue-item-id:::output
classDef required fill:#6ba06a,stroke:#333,stroke-width:3px
classDef optional fill:#d9b430,stroke:#333,stroke-width:3px
classDef action fill:blue,stroke:#333,stroke-width:3px,color:#ffffff
classDef output fill:#fff,stroke:#333,stroke-width:3px,color:#333
click token "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L9"
click title "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L15"
click body "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L20"
click labels "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L25"
click assignees "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L30"
click project-type "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L36"
click project "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L11"
click column "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L49"
click milestone "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L55"
click pinned "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L60"
click close-previous "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L67"
click linked-comments "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L74"
click linked-comments-new-issue-text "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L82"
click linked-comments-previous-issue-text "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L89"
click rotate-assignees "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L96"
click issue-number "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L104"
click previous-issue-number "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L107"
click project-v2-issue-item-id "https://github.com/imjohnbo/issue-bot/blob/main/action.yml#L117"
The issue body is treated as a Handlebars template, with support for template variables:
assignees
: The array of issue assignees.previousIssueNumber
: The previous issue number in the series.
The linked comments (linked-comments-new-issue-text
, linked-comments-previous-issue-text
) support these variables and:
newIssueNumber
: The new issue number.
Issue Bot requires an API token, customizable with the token
input, to authenticate with the GitHub API. The default GITHUB_TOKEN
should work for all use cases except project
and project-v2-path
, when its permissions aren't sufficient. Please use a GitHub App installation access token of a GitHub App with repository/project:read-write
/organization/project:read-write
scope or personal access token with project
scope in these cases.
GitHub Apps are in general pretty cool and offer some nice advantages over personal access tokens, so they're preferred when possible.
GitHub App installation access token:
# ...
# Generate installation token for your GitHub App with...you guessed it, an action
# See https://github.com/tibdex/github-app-token for setup
- name: Generate token
id: generate_token
uses: tibdex/github-app-token@v1
with:
app_id: ${{ secrets.APP_ID }}
private_key: ${{ secrets.PRIVATE_KEY }}
# New standup issue generated with a GitHub App!
- name: New standup issue
uses: imjohnbo/issue-bot@v3
env:
TOKEN: ${{ steps.generate_token.outputs.token }} # installation access token as output of previous step
with:
title: Standup
body: |-
... standup template ...
token: ${{ env.TOKEN }}
# ...
Personal access token:
# ...
# New standup issue generated with a personal access token
- name: New standup issue
uses: imjohnbo/issue-bot@v3
with:
title: Standup
body: |-
... standup template ...
token: ${{ env.PAT }}
# ...
Issue Bot currently supports Projects (a.k.a. Projects v2, Projects Beta, and Projects Next) (project-v2-path
) and Projects (classic) (project
, project-type
, column
, and milestone
). See action.yml
for more details about these inputs.
Except when adding an issue to a Projects (classic) repository board, where the built in github.token
's permissions suffice, it's recommended to use a GitHub App installation access token or personal access token with the proper scopes.
Support for Projects (classic) will be dropped in a future version.
Feel free to open an issue, or better yet, a pull request!