philschatz/project-bot

:octocat: Automatically add and move Issues/Pull Requests on a Project board

project-bot

Do you like the idea of GitHub's Project Automation feature but find it lacking?

This bot will automatically add new Issues or Pull Requests to a Project board based on specially formatted Cards in each Column of a Project. It also allows you to customize the rules for moving Issues between Columns.

Installation

Go to the project-bot GitHub App page and click [Install] (or [Configure] if you already installed it) to have it run on Public Project Boards.

To see what it looks like, you can look at the GitHub projects for this repository.

Example

To create an Automation Card, create a Card in a Project like this:

###### Automation Rules

<!-- Documentation: https://github.com/philschatz/project-bot -->

- `assigned_issue`
- `closed_issue`
- `added_label` **wontfix**
- `new_pullrequest` **repo1** **repo2**

Now, whenever any Issue that is assigned, or closed, or a wontfix label is added, or a new Pull Request is opened on the repo1 or repo2 repository will show up in this Column.

Syntax

This bot uses normal Project Board note cards with Markdown formatting for configuration.

Automation Cards

• Automation Cards are identified by the string ###### Automation Rules that has to be used in the note text
• The automation card must be at any the top or bottom of a column (but they tend to end up at the bottom as new cards are added at the top automatically)
• There can be multiple automation cards per column, but you will probably not need that (unless you have many rules or add items from many repositories)
• An automation card can contain other text besides the headline and rules if you really need it to (but best avoid other lists to confuse the parser)

Rules

• Rules have to be listed in an unnumbered list in the Automation Card
• This list can contain as many rules as you like
• The rule (see list below) should to be wrapped in ` like so:

  - `example_rule`
  

• Rule Parameters should be wrapped in ** like so:

  - `example_rule` **param 1** **param 2**
  

• Items are added or moved into the column when any of the rules in the list are triggered. (It is currently not possible to use boolean logic to combine any rules.)

Available Rules

The following rules can be included in automation cards:

Add items

To add items to the project board, you have these two rules:

• new_issue: When an Issue is created (optionally, a space-separated set of repo names)
• new_pullrequest: When a Pull Request is created (optionally, a space-separated set of repo names)

Move items

After an item has been added to a project board (manually or by the previous rules) it can be moved to another column by one of the following rules:

Issues

• edited_issue: When an Issue is edited
• assigned_issue: When an Issue is assigned to a user (but was not before)
• assigned_to_issue: When an Issue is assigned to a specific user
• unassigned_issue: When an Issue is no longer assigned to a user
• milestoned_issue: When an Issue is added to a Milestone
• demilestoned_issue: When an Issue is removed from a Milestone
• closed_issue: When an Issue is closed
• reopened_issue: When an Issue is reopened

Pull Requests

• assigned_pullrequest: When a Pull Request is assigned to a user (but was not before)
• unassigned_pullrequest: When a Pull Request is no longer assigned to a user
• added_reviewer: (optional username or array of usernames that need to be added)
• accepted_pullrequest: When at least one Reviewer Accepted, and there are no Rejections on a Pull request
• merged_pullrequest: When a Pull Request is merged
• closed_pullrequest: When a Pull Request is closed
• reopened_pullrequest: When a Pull Request is reopened

Labels

• added_label: (requires exactly one argument, the string representing the name of the label)
• removed_label: (requires exactly one argument, the string representing the name of the label)

Other

• Not finding the event you would like? Just create a new Issue in this Repository!

Screencap

project-bot's Issues

Close issues automatically?

It would be nice to have some rule that closes issues automatically.
Like for example you have label v0.4.12 and you want to close all issues when tag v0.4.12 is released.

Don't know if this would be posible with the current sytem you've got going here... but could look something like:

• Repository has label: v0.4.12

###### Automation Rules
- `tag_release` close-issues-for-tag

If this is not posible with your bot, do you know of anything that could help me achive this? If not I will do something myself.
Cheers!

feat: Add unit tests

The underlying library, probot, recommends using jest and nock to play back webhook events.

It seems like nock can replay requests but I am not sure if it can record them. In the past, I have used fetch-vcr to record and play back HTTP requests with varying levels of success.

This should help catch bugs in Pull Requests and increase confidence when upgrading dependencies.

[BUG] automation seems to have stopped

Cards are no longer being moved from column to column when I apply a tag. This has been working without an issue for some time and appears to have stopped either today or within the past two days.

• My automation cards are at the bottom of my columns
• the tags match the tags specified in the cards

I have not made any changes to the automation rules or tags recently, not sure what's going on here. I do not see a way to message, I hate to add an issue, but can someone help?

Feature: Move task "In Progress" if a commit message is mentioning it

Would be nice to be able to move an issue (not a pull request) in a column when the first attempt to fix/implement it was made.

Can't delete card

For some reason if I try to move a configuration card, edit it or delete it (basically any action), Github returns an error, asks me to refresh and does nothing...

Other cards work fine

Feature request: New Event: Move issue when issue have new reply

It would be nice to add event .

Questions on params

Before I start nitpicking on small things, let me say I absolutely love this project and am absolutely planning it on some repositories with loads of PRs and issues - it will be such a great help if I actually get it working as I need it to.

---

added_label: (has one argument, the string representing the name of the label)

• Does that mean added_label only works with 1 label?
• How can I achieve a column for two or more labels? Add added_label twice to the config?
• Can I somehow also move an issue/PR as soon as any label is added?

2. Bolding of parameters

The example uses ** around the parameters. The example project board doesn't seem to use it for all params.

What is the difference?
Must one use **?
Or can one just use **?

Feature: Add minimum_approval filter

When the PR reaches the minimum number of approvals, which differ from project to project, then move it to specific lane

Feature request: Add label "foo" when item moved into column "bar"

Right now we can move items when a label has been assigned. It's also useful to have the opposite workflow, so e. g. when I move something into the "QA" column, give the issue/PR a "in-qa" label.

Why? Our team uses the board to move items but we are using labels to filter specific issues by label (since projects don't offer this feature).

[Question] Why limiting the creation of cards to new_issue and new_pullrequest ?

Hi @philschatz,

I looked at your bot and I would be interested in creating cards when my tickets have a specific label.

It seems in the commands.js, only the new_issue and new_pullrequest are creating a new card. What is the limitation of setting createsACard: true on other events ?

For instance:

  {
+   createsACard: true,
    ruleName: 'added_label',
    webhookName: 'issues.labeled',
    ruleMatcher: async function (logger, context, ruleArgs) {
      // labels may be defined by a label or an id (for more persistence)
      return context.payload.label.name === ruleArgs[0] || context.payload.label.id === ruleArgs[0]
    }
  },

[Issue] - multiple added_label not working

If I add multiple added_label rules to a card, it appears that only the last one is used. In Example 1 below, when I apply Label_3 to a card it is moved to the specified column. However, if I apply Label_1 or Label_2, the cards are not moved unless I reorder the Automation Rules moving the desired rule to the bottom. In Example 2, cards with Label_2 are moved to the specifiied column.

Example 1

Automation Rules

• added_label Label_1
• added_label Label_2
• added_label Label_3

---

Example 2

Automation Rules

• added_label Label_1
• added_label Label_3
• added_label Label_2

Assign issue to specific project

If there are many projects in a repo, it'd be great to be able to assign the issue to a particular project based on a specified parameter.

Some card(s)/column(s) sometimes fail(s)

Note that each comment here represents another step of my investigation of this bug. The first message is my first idea, the second comment adds more insight etc. I updated the issue title to reflect the last state, but left the comments themselves alone.

---

I was just debugging some columns with automation cards not working. A column on the right of my board didn't work, which didn't make sense as the exact same configuration card had worked earlier more to the left.

Seems that a column with a merged_pullrequest card causes a closed_pullrequest column/card to fail:

###### Automation Rules
- `merged_pullrequest`

And right to it:

###### Automation Rules
- `closed_pullrequest`

When I moved the closed_pullrequest card to the left of the merged_pullrequest one, closed PRs were moved to the correct column again.

(I unfortunately couldn't test the merged_pullrequest at all because I have no real testing repository)

Probably caused by the similarness of closed and merged?
Maybe they block each other somehow?

Feature: Pending approval by reviewer

Github automation has a "Pending approval by reviewer" rule to move cards if a reviewer requests changes on a pull request or the minimum number of necessary approvals is not met yet.

[Issue] Trigger label not triggering when multiple labels are attached at once.

You can see an example of this issue in the history here:

Steps to Reproduce

1. Have a label Ready.
2. Have a rule card like:

###### Automation Rules

<!-- Documentation: https://github.com/philschatz/project-bot -->

- `added_label` **Ready**

3. For an issue already in the project, add the labels Ready and another label at the same time.

   At this point project-bot does not move the issue.

4. Remove and re-add the label Ready by itself, at which point the card is moved.

Rules in configuration cards

Same disclaimer as on my other issue(s): I absolutely love this project and am absolutely planning it on some repositories with loads of PRs and issues - it will be such a great help if I actually get it working as I need it to.

---

• Do the rules have to be wrapped in ` to work?
• Be in a list?
• Could the ordering of rules be relevant in any way?

Automation only works when project exists inside a repo that the bot is configured for

Github allows projects to exist inside, and outside of repositories. In attempting to give this a trial run, I noticed that the automation does not appear to work if the project exists outside of the repository (at the user or organization level), even if you specify a repository name within the automation card.

If this isn't an easy fix, it would be helpful if the documentation at least made this clear.

[feature request] existing review request for new PR

When a PR is opened, the new_pullrequest rules correctly adds it to the correct board.
After that, if a reviewer is added, the added_reviewer rule correctly moves it to the correct board.

However, if a PR is opened with already added reviewers, the above rules don't work properly, where the new_pullrequest rule adds it to the "new PR" board but it never gets moved to the "review necessary" board because the reviewer was added before the PR was added. The added_reviewer rule never triggers.

This also happens if someone opens a new PR and within a few seconds adds a reviewer before the project-bot adds it to the project board.

I guess this request is for conditional rules. For instance, new_pullrequest could be combined with added_reviewer to add it directly to the "review necessary" board if both conditions are fulfilled. If not, it gets added to "new PR" board.

Thanks

[Issue] - New Card trigger not working.

The trigger card on my project is formatted as:

###### Automation Rules

<!-- Documentation: https://github.com/philschatz/project-bot -->

- `new_issue` **documentation**

It's at the bottom of the Inbox column. New issues to the documentation repo are not added to the project.

[Feature Request]: Search for Milestones

Would be nice to Add only Tickets that are in a certain Milestone.

[Feature Request]: Set up Template Tickets

All the Ticket look different and have no labels. I think would be better when GitHub Template issues would be used.

[feature request] Support User Level Projects

I think it may be better to support user-level projects.

Move Issue when Issue is Moved in other Project Boards

If an issue is moved on another project board to a new column (ie. In Progress, Code Review, etc), that it moves to the same column on other boards as well. This allows certain teams to monitor only 1 board without having to manually move Issues around on several boards.

ie. Team 1 (build team) uses Project Board 1 to track the Issues they're working on.
Team 2 (requirements gathering team) uses Project Board 2 to track Issues they're grooming.

When Issue on Project Board 2 is moved to 'Build Ready', it should be auto-added to 'To do' in Project Board 1.

When Issue on Project Board 1 is moved to 'Code Review' it should be auto-moved to 'Code Review' column on Project Board 2.

When Issue is moved to 'done' on either Project Board, it should move to 'Done' on all other Project Boards.

Special charters in label []

Dosent special charters work in add label ?

<!-- Documentation: https://github.com/philschatz/project-bot -->
- `added_label` **[zube]: To do**

this dosen't work :/

Suggestion: milestoned_pullrequest

Follow-on from #26 (comment)

There already is a milestoned_issue rule, but sometimes a PR is created by a contributor without a separate Issue first. A milestoned_pullrequest rule would allow these PRs to be automatically moved within a board as well.

added label

Hi

I am trying to set this bot up for the official Joomla repository here https://github.com/joomla/joomla-cms/projects/13

The bot is working because I successfully tested the rule new_issue

However I am unsuccessful in getting the bot to work with the rule added_label

- `added_label` **J3**

Am I missing something obvious?

Configuration cards?

Same disclaimer as on my other issue(s): I absolutely love this project and am absolutely planning it on some repositories with loads of PRs and issues - it will be such a great help if I actually get it working as I need it to.

---

What are the actual requirements on the "configuration cards"?

• Do they need the ###### Automation Rules string to be considered configuration? What makes a card a configuration if not?
• Can there be multiple of those cards per column or does it have to be one per column?
• Does the card have to be at a specific location in the column to be picked up?
• Any other specifics one should know about for the configuration cards?

Feature: added_label (without parameters)

Can I somehow also move an issue/PR as soon as any label is added?

hmm, this is not currently possible but it seems like it could be added. Then, one could just write added_label

Source #14 (comment)

Add Issue/PR the Project, when assigned to a milestone?

Would it be possible to add functionality, such that Issues and PRs assigned to X milestone get put in X project (and then existing rules could presumably automatically put that in a particular column.)?

Right now, the readme suggests that milestoned_issue can only be used to move a card once it has already been added.

What we don't want is to require that all issues automatically get added to a project.

Licensing Model

Hi

Is there any licensing model or can this be used in any projects for enterprise software gits?

Regards
Clarissa

Only already added issues and PRs are affected by automation? (except `new_*` of course)

Did I understand correctly that only issues or pull requests that are already part of the project board are affected by project-bot rules?

Exceptions of course are the 2 rules to add issues and PRs to the borad in the first place, new_issue and new_pullrequest.

An in-range update of probot is breaking the build 🚨

The dependency probot was updated from 9.9.5 to 9.9.6.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

probot is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Status Details

• ❌ Travis CI - Branch: The build errored.

---

Release Notes for v9.9.6

9.9.6 (2020-02-24)

Bug Fixes

• package: update uuid to version 7.0.0 (#1146) (c6551d0)

Commits

The new version differs by 1 commits.

• c6551d0 fix(package): update uuid to version 7.0.0 (#1146)

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Rename added_label to added_issue_label

and add an added_pullrequest_label since those are different webhook events

[Feature Request]: Add existing Issues

It would be nice to have the possiblity to add existing cards to the Kanaboard. Or an initialisation button to get the new Tickets automatically in the Project.

Project bot always breaks because some actions move automation cards from the top/bottom slots of the column

I think you might already be aware based on your comment here, but the current constraint of requiring the project-bot automation cards to be at the top or bottom of the column breaks project-bot often.

For instance, earlier, I requested the a teammate make changes to a pull request, which moved the pull-request card to the bottom of the column, underneath the automation card (which was previously at the bottom, because that seems the most stable position), which in turn broke automation for the column, which creates manual work that nobody even knows needs to be done!

This constraint seems like a big risk for this otherwise really useful solution. Project-bot definitely has made our lives easier, but has potential to an invisible backlog of manual work due to the top/bottom of column requirement.

[Question] read access to single file

In the app's permissions:

Read access to issues, metadata, pull requests, and **single file**

I've checked what single-file access means, but I don't see how it's used/needed in project-bot.

Thanks in advance! :)

[Issue] - Automation rules must appear at the top or bottom of the column in order to run.

The automation rules are not running unless the Automation Rules card is located at the top or bottom of the list. If the card is located between two or more issues the automation rule is not applied.

Doesn't work with organizations?

Issue: mlr-org/mlr#2309
Project board: https://github.com/orgs/mlr-org/projects/1

I assigned the label and removed it but nothing happened in the board.

Maybe because the project board is in the organization and not directly in the repo?

Bot doesn't move issues to project cards

Welcome! This bot doesn't work properly. I have errors

�[39m�[90m20:52:06.517Z�[39m �[32m INFO�[39m http: �[36mPOST / 200 - 6.53 ms�[39m�[90m (id=4ba641cf8a0eb4c9)�[39m

�[90m20:52:06.518Z�[39m �[31mERROR�[39m event: �[36merror:0906D06C:PEM routines:PEM_read_bio:no start line�[39m�[90m (id=2bba8f40-50a6-11e8-9cbc-9731bd16da70)�[39m

�[90m  Error: error:0906D06C:PEM routines:PEM_read_bio:no start line

     at Sign.sign (crypto.js:331:26)

     at Object.sign (/rbd/pnpm-volume/b03eac61-ede1-4ef0-8dd6-b41e8ac14e73/node_modules/.registry.npmjs.org/jwa/1.1.5/node_modules/jwa/index.js:55:45)

     at Object.jwsSign [as sign] (/rbd/pnpm-volume/b03eac61-ede1-4ef0-8dd6-b41e8ac14e73/node_modules/.registry.npmjs.org/jws/3.1.4/node_modules/jws/lib/sign-stream.js:23:24)

     at Object.module.exports [as sign] (/rbd/pnpm-volume/b03eac61-ede1-4ef0-8dd6-b41e8ac14e73/node_modules/.registry.npmjs.org/jsonwebtoken/8.2.1/node_modules/jsonwebtoken/sign.js:189:16)

     at Robot.app (/rbd/pnpm-volume/b03eac61-ede1-4ef0-8dd6-b41e8ac14e73/node_modules/.registry.npmjs.org/probot/6.1.0/node_modules/probot/lib/github-app.js:12:16)

     at res.cache.wrap (/rbd/pnpm-volume/b03eac61-ede1-4ef0-8dd6-b41e8ac14e73/node_modules/.registry.npmjs.org/probot/6.1.0/node_modules/probot/lib/robot.js:149:63)

     at <anonymous>

     at process._tickDomainCallback (internal/process/next_tick.js:228:7)

Conditional Logic

Hey!

I've been looking for a way to automate my project board, so I can get a better overview over some of my projects, and found this.

One thing I couldn't see was if there is any form of conditional logic?
That is, I want to have an "In Progress" column that reacts to added_label **inprogress**, but only if there is also another label on it, and so on.

My use case is that I have a private repo with lots of different issues in (Work, Open Source stuff, Personal stuff etc), and I currently tag them all as such so a given issue could have two labels: work, inprogress or personal, inprogress.

Because of this, I can't setup an added_label rule, since if I stick that in both my Work and Personal project, then the issue is applied to both projects, rather than just one of them.

What I guess I'm looking for is:

###### Automation Rules

- `added_label` **wontfix**
- `has_label` **work**

Or maybe my lack of experience with Projects means I'm doing something entirely wrong! I could swap to per project labels, but it sounds messy to duplicate everything.

Problem adding a new issue by label to multiple projects

👋 Hello!

I have two projects. Each with project-bot configuration cards. The first project's card looks like this:

###### Automation Rules

- `new_issue`
- `added_label` **type: bug 🐛** **type: a11y ♿** **type: question**

The second project's card looks like this:

###### Automation Rules

- `new_issue`
- `added_label` **type: a11y ♿**

When I add a new issue to the repository only the the first project gets the new issue. Didn't see adding a single card to multiple projects mentioned explicitly in the documentation so I'd figured I'd ask if this functionality is currently supported.

Thank you so much for your hard work.

Private repos in orgs

Are they supported?

Possible source for problems?

What happens if someone creates an issue and adds a label during creation - and I have a new_issue automation and a added_label automation for that label? (Similar source for problems with assignment, milestone etc.)

Feature: automatically assign user(s)

I would like to be able to assign user(s) when a card is moved (manually or automatically) to a column. I have a 'Blocked' column and would like to be notified when a card is added to the column.

Card Awaiting Triage

Thank you for this bot. It's very useful.

I have a "To Do" column with the following note:

###### Automation Rules

<!-- Documentation: https://github.com/philschatz/project-bot -->

- `new_issue`
- `unassigned_issue`
- `reopened_issue`

When I create an issue in this repository, it is automatically added to the project board and added to the "To Do" column. However, if I go to the issue take it off the project and then change it back to the original project, instead of getting added to the "To Do" column, it gets put in triage. Is there a way to automatically have issues that are reassigned to the project added to the "To Do" column?

added_label / removed_label only works for the last label specified

I'm trying to use rules in https://github.com/alpinelinux/aports/projects/1#card-21871246 but nothing is done when the label is removed.

You can see my attempt to remove S-WIP on alpinelinux/aports#9510

I've determined that only the last removed_label rule is working. When I swapped the order of S-stale and S-WIP then the rule that did not work changed.

Similarly, for the rules in https://github.com/alpinelinux/aports/projects/1#card-21870936 only the last entry for added_label is working.

I think I figured out the cause.

project-bot/src/extract-rules.js

Line 41 in 05ca4f9

parsedRules.set(node.literal, args)

The later rules overwriting earlier arguments could be solved by using an array instead of a Map or the hooks could be changed to operate on a list of label arguments. Which solution do you prefer? @philschatz

Feature: has_labels

If you want a column to have issues when either Label1 or Label2 are added then you can have a 2-item list:

• added_label Label1
• added_label Label2

Having cards move when they have Label1 and Label2 is not currently possible but maybe something like has_labels Label1 Label2 could be added in the future

Source: #14 (comment)

[feature request] add author based rule

I think it would be great if there was a new rule based on issue or PR author, which could accept a list of usernames.

On our organization's project board, it would be nice to automatically separate PRs coming from team members vs non-members.

Thanks

[Feature Request] Determine Card Placement / Order

I would like to be able to define a rule such that when a card is moved into a project or column, it will go to the bottom of the stack instead of the top.

Alternately, consider making this the default, which would match the behavior of the new widget provided on Issue / PR pages to move items between columns.

New action: flagged as duplicate

see subject