alexellis / derek

Reduce maintainer fatigue by automating GitHub

derek

Derek reduces fatigue for maintainers by automating governance and delegating permissions to your team and community.

Follow @derekapp on Twitter.

User guide / documentation

From the team that brought you OpenFaaS - Serverless Functions Made Simple.

Core features

All features are modular and can be enabled/disabled as required:

• Generate changelogs for releases with PRs merged and commits added
• Let designated non-admin users manage Issues and PRs by commenting Derek <command> or /command
• Enforce Developer Certificate of Origin (DCO) checking (optional)
• Automatically label/flag PRs without a Description
• Label PRs from first-time contributors
• Detect spam PRs (from hacktoberfest)
• Automatically close PRs during hacktoberfest from first-time contributors

For the managed service the cost is 25USD per month. You will need to become an OpenFaaS GitHub Sponsor to gain access to the managed service. The price covers hosting, management and maintenance of the service.

Built for developers by developers

User guide

Find out what Derek can do you for your project, community and team including all available commands and configuration options

Read the user guide

Start using Derek today

Get started here: Onboarding guide

How do I work?

I'm designed to be installed as a GitHub App, but don't worry - I don't need a lot of permissions. Just access to issues and Pull Requests will do.

I'm not a long-running daemon.. I'd get bored that way. I work with webhooks - so deploy me to a Serverless platform like OpenFaaS and forget about me. Just apply oil from time to time.

This is me in action with the DCO-checking feature. If I find a commit that isn't signed off then I'll let the contributor know in a comment. Normally they edit their commits and re-push within a few minutes after re-reading the message.

Inspiration for Derek

The idea for a bot that could comment on issues or respond to activity is from the docker/docker or Moby project's bot called Poule. It's a much more complex long-running daemon which uses Personal Access Tokens (so needs to run as a full GitHub login). Derek is much simpler (so hackable) and can be installed with granular permissions.

Live demo here

Our users

Some of our users include:

• Docker / Moby
• okteto
• OpenFaaS
• inlets
• arkade
• k3sup

Backlog:

• Derek as a managed GitHub App (SaaS)
• Lock thread
• Edit title of Issue/PR
• Toggle the DCO-feature for those who don't need compliance
• Show help messages such as how to join Slack or asking for a rebase via Derek message
• Automate release notes based upon PRs closed
• Add each commit to release notes

Future work:

• Add merge feature based upon policy (in-progress)
• Caching of customers / .DEREK.yml file
• Observability of GitHub API Token rate limit
• Add roles & actions
• PR target branch checking (i.e. no PRs from master to master)

Maintainers and contributors

There are over a dozen contributors to Derek, but the following people have made the most impact.

Maintainer(s):

• Alex Ellis - creator & lead maintainer

Hall of fame:

• Martin Dekov - @martindekov
• Burton Rheutan - @burtonr
• John McCabe - @johnmccabe
• Lubomir I. Ivanov - @neolit123
• Ivana Yovcheva - @ivanayov
• Richard Gee - @rgee0

Alex Ellis created Derek to automate project maintainer duties around licensing and to help bring granular permissions back to GitHub. Derek has empowered contributors in the OpenFaaS community to run and maintain the project without needing full write access. OpenFaaS contributors continue to improve Derek so they can get the job done without fuss.

Contributions

Please follow the OpenFaaS contribution guide.

derek's Issues

Suggestion: SDK for Derek

Would it be useful to provide Derek as an SDK?

The GitHub auth that we've written has already been useful for the GitHub App in OpenFaaS Cloud and could be useful as a separate package.

Due to forking of Derek over one user not wanting to follow DCO process, would it be advantageous for us to release Derek as an SDK so the functionality can be invoked via other processes such as a regular HTTP server or as suggested in another issue - an AWS Lambda function? #13

If Derek was packaged as an SDK a few things would need to change:

• secrets would have to be read ahead of time into memory and passed in a configuration object
• any log.Fatal* lines may need to be removed
• regression testing would also be needed
• updates to docs for consumption of SDK

Add contributing field to .DEREK.yml

Expected Behaviour

We need to be able to specify a "contributing_url" field for when Derek is used across an organisation or many repos. The "redirect" flag now means many Derek files are just redirecting to another repo for rules - at least in OpenFaaS we don't need separate contributing guides.

Current Behaviour

I create a Markdown page with a link to the openfaas/faas contributing guide but sometimes forget and that's not a great experience because new developers get linked to a 404.

Possible Solution

Add field contributing_url and use that when given, otherwise use the existing behaviour.

Derek to populate release notes from matching PRs/Issues with milestone

So now that we have milestone support it would be good to have Derek help compile the description for releases by reacting to the event fired and then doing a quick search and populating the text i.e.

Changelog:

- PR x by username

This would be an optional feature.

Derek set milestone: current/next

Needs more thought - but I can't always remember what milestone number to pick when doing this on mobile for instance.

Derek set milestone: 0.5.4

vs:

Derek set milestone: next

Which could be: 0.5.5

Derek add milestone -> Might just add the latest one available.

There are other tools that can generate change logs but this seems like a simple feature to explore more.

Research task: automate creation of GitHub App

Can we make development and testing easier by automating the creation/config of the Github App via the GitHub API?

Ideal flow:

• User creates personal access_token
• User runs derek --provision-app --name="Derek PR 68"
• GitHub App created and then access token revoked?

Research into: Derek rebase (depends YAML 2.0)

If we implement Roles 2.0 #22 then we could add "Derek rebase" and set up permissions for who can run this command and what the validation is.

i.e.

• no conflicts with base branch
• is allowed to merge
• has N LGTM

I have a PoC that works, but it has no policy beyond being in the curators section.

App ID hardcoded in GetSignedJwtToken function

Expected Behaviour

Following the README should be sufficient to deploy and run your own Derek instance.

Current Behaviour

The generated JWT tokens are invalid.

Possible Solution

Replace the hardcoded App ID in jwt_auth.go with one sourced from the env.

Context

Unable to get own Derek instance running, positive side tho is that I now know a lot more about Githubs App auth 😄

Your Environment

• Docker version docker version (e.g. Docker 17.0.05 ):
  17.06.1-ce

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?
  Swarm

• Operating System and version (e.g. Linux, Windows, MacOS):
  Ubuntu 17.04 on DigitalOcean

• Link to your project or a code example to reproduce issue:
  n/a

Move Derek to latest Golang version

Task:

1. Try moving the Derek Dockerfile to the latest Go version and build.
2. Fix any issues
3. Send PR

Switch to HMAC package upstream

We can now remove the hmac.go code and vendor it:

https://github.com/alexellis/hmac

Good beginner issue

Tag PRs from new contributors as derek/first-time

This is a suggestion to help with first impressions and helping new contributors to a project/repo.

To help users identify and give help to new contributors to a repository Derek could add a label such as derek/first-time or derek/new-contributor

This metadata may be represented in the metadata already of a GitHub push/PR - https://developer.github.com/v3/activity/events/types/#pushevent

Alex

Derek adds a label when labelling comment is deleted

Course of action to reproduce:

Derek add label: fred <-- label added
Derek remove label: fred <-- label removed
Delete comment 1 <-- label added again

Potential fix would be to inspect the POSTed JSON to see if "action": "deleted" is set and cause Derek to refuse to act within AddLabel and RemoveLabel in this instance. Within the code this would be req.Action

Prevent removal of "no-dco" label

I noticed that a contributor had Derek installed on one of his repos. He had a PR arrive without sign-off and Derek added the no-dco label.

The developer removed the label then merged the PR.

I would suggest that we prevent Derek from responding to "Derek remove label: no-dco" for the above reason.

Those with write-access can still remove it via the UI controls.

Backlog: check if PR template was deleted

Scenario: impatient contributor deletes whole PR template message and decides it doesn't apply to them.

Result: PR is decorated with a comment telling user to fill out PR template.

Implementation ideas:

Opt in via feature in .DEREK.yml file pr_template_checking

• v1.0 PR body cannot be empty
• v2.0 100% of the lines beginning with a heading i.e. # in repo/.github/PULL_REQUEST_TEMPLATE.md must be present in body of PR

@rgee0 @dirkhh @johnharris85 thoughts?

Proposal: Check the branches that PRs are raised against and from

Upon submission of a PR Derek should check the originating branch name, and if he finds master the PR closed with a message advising the user that they should re-submit from a non-master branch.

Also, check that pull request is against master / default.

Proposal: Feature to check that a PR description includes closure keywords

Expected Behaviour

Addition of a new feature to check the contents of a PR description for a referenced issue number. See: https://help.github.com/articles/closing-issues-using-keywords/ for a full explanation.

Current Behaviour

A PR is raised with an issue reference but without a closure keyword. This results in manual activity to keep repo issues in sync with project state.

Possible Solution

Similar to the sign-off check. Test the incoming detail for GitHub closure keywords:

close
closes
closed
fix
fixes
fixed
resolve
resolves
resolved

alongside an issue reference. Further detail on the format of these is available at the aforementioned link.

On receipt of a PR without a closure Derek should apply a label, such as no-issue, unlinked, no-closure and post a comment to provide the user with the information required to help them update the description.

Steps to Reproduce (for bugs)

Not a bug

Context

Enabling the ability for Derek to apply more of a project's contributing guide through contributor education & prompting.

Your Environment

N/A

Posibility to pass multiple values to an action

It would be great to be able to send multiple values in the same action, i.e:

Derek add label: UX, enhancement, proposal (, as separator, more natural)
or
Derek add label: UX || enhancement || proposal (|| as separator)

I can work on this if the proposal is accepted

Add support for closing/reopening issues/PRs

Expected Behaviour

Derek should allow Maintainers to close and reopen issues and PRs.

Derek close: mandatory reason text
Derek reopen: mandatory reason text

Suggestion: Allow any prefix such as "/" or another name as Derek trigger

A PR was raised to enable users to invoke Derek via another prefix such as "/" in #56, but the code was not signed-off and the patch could not be merged.

This is a suggestion for third-party usage of Derek outside of the OpenFaaS project. I think this is a good beginner issue.

.DEREK.yml 2.0 - YAML roles

Version 2.0 of .DEREK.yml would be:

roles:
  - role: curator
     actions:
       - labels
       - close_issue
       - open_issue

  - role: maintainer
     actions:
       - close_issue
       - open_issue

users:
  - name: alexellis
    roles:
      - maintainer
  - name: rgee0
    roles:
      - maintainer
      - curator

features:
 - dco_check
 - comments

Proposal: Derek should lock / unlock threads

Threads in PRs and Issues should be lockable by issuing Derek lock and unlock-able by issuing Derek unlock

Issue with HMAC secret when using a file

Issue identified by @MrTinD

Expected Behaviour

A secret for derek-secret-key (for HMAC) should be read from a file when needed i.e. docker secret create derek-secret-key ./derek-secret-key

Current Behaviour

When creating the HMAC secret via docker secret create derek-secret-key ./derek-secret-key we get an extra new-line in the data we read and that makes the validation of HMAC fail because in the GitHub UI we can only enter a single line of text.

File:

my-secret\n

GitHub:

my-secret

Possible Solution

1. Work-around - use echo -n | docker secret create derek-secret-key - to suppress the new-line terminator in the file.

2. Change code to always strip down any new-line characters when reading the HMAC secret.

Steps to Reproduce (for bugs)

1. See above

Context

Caused frustration for user submitting patch, we need to make this better.

Your Environment

• You're using the hosted Derek service

or

• You host your own OpenFaaS cluster with Derek installed

• Docker version docker version (e.g. Docker 17.0.05 ):

  Version:      18.05.0-ce

• Are you using Docker Swarm or Kubernetes (FaaS-netes)?

We're using Docker Swarm but this may apply to Kubernetes too.

[Proposal] Add feature to auto label issues when an associated PR is raised

Add a new feature so that when a contributor opens a PR and refences an issue, or multiple issues a label is automatically applied to the issue(s).

This could help contributors filter out at the top level those issues which are currently in progress / being addressed.

Revisit: GitHub Checks / Commit statuses

Expected Behaviour

We looked into this before in a previous issue, but I think we could leverage GitHub Checks or commit statuses to give feedback on the DCO and other things Derek checks.

#35

Current Behaviour

We post a label and a comment when one of the commits in a PR isn't signed off, but this still allows merging through the UI and some newer contributors don't understand that every commit needs to be signed-off-by - not just the last one.

Possible Solution

Prototype working with a commit status / check where one of several commits in a PR is detected as invalid to see if this can fail the whole check. The feedback given before by @stealthybox said only the final commit in a series determines the pass/fail of a PR (but we should check again)

Add more docs for "Github app" section of install

I'm a little stuck on the "Install Derek as a GitHub app" section as I can't find it on the marketplace as most "Github apps" are.

So then I'm guessing I have to create my own Github app? If so could you help with what these fields will needs to be filled with.

I already have a publicly facing openfaas gateway that I can use.

(Also might be an idea to link to the Github app registration page.)
https://github.com/settings/apps/new

 

Delete command after execution

Any chance derek could delete the command comments in the issue/PR after the command is executed?

Support for other environments

Would you be open to add examples for deploying it to AWS Lambda with something like apex/up or zeit/now . I probably could help with those.

Consider supporting .github directory for DEREK.yaml

GitHub supports a .github directory to reduce the amount of clutter in a projects root directory for issue and contribution docs. It would be nice if DEREK.yml could also be placed there.

A potential downside is that GitHub owns the .github namespace. Alternately a directory named .automation would be nice for this type of configuration data, but pointless if only Derek uses it.

Proposal: send messages to Slack channel

In order to monitor and observe usage of Derek we should offer the ability to send messages to a Slack channel.

All usage of Derek via comments / PRs is public so I do not see any concerns with this going to one place.

It will give an overview at a glance whether there is any recent activity, by which installations and which users.

Example of status messages sent to Slack:

• a no-dco label is added to PR 131 in repo openfaas/faas-cli
• a label is applied to issue 586 on the openfaas/faas repo by @AlexEllisUK

This would use the incoming web hooks feature rather than any specialist library and could be swapped for any other HTTP endpoint. Slack messages have a basic format of:

{
   "text": "Message to channel goes here"
}

Update secrets path

In a conversation with @alexellis we saw an issue in Derek using the latest master version of openfaas.

failed to report status github.RepoStatus{State:"success", TargetURL:"http://<domain>:8080/function/alexellis-hallo", Description:"function successfully deployed as: alexellis-hallo", Context:"DEPLOY"}, error: unable to read private key path: /run/secrets/derek-private-key, error: open /run/secrets/derek-private-key: no such file or directory

This is due to openfaas/faas#692

Possible Solution

Update the path to search /var/openfaas/secrets

Proposal: Announce GH Releases

It would be useful to be able to enable Derek to automatically announce releases to an organisation's twitter account, for instance.

Travis should push Docker images when we cut a new release

Any time we cut a new release of Derek we should be publishing a new Docker image to the Hub.

See openfaas/faas or openfaas/faas-netes for an example in .travis.yml and any other Makefiles.

Add support for `assign reviewer`

At the moment Derek cannot assign reviewers to a pull request.

Support comments like:

Derek assign reviewer: username

Good option is to make it work with a list of users:

Derek assign reviewer: user1, user2

Config redirect with local repo-based overrides

Expected Behaviour

The config redirect which means a local repo can have just a single entry "redirect_url: https://" rather than a complete .DEREK.yml file has been really useful across the dozen or so OpenFaaS repos. There are times where a local override is needed for a specific repo.

I would see this working as an intersection with the local override taking precedence. This would also be useful for the rebase feature in #91.

There may be a generic config set up in the "main" repo - all other repos may point there defining "@alexellis has rebase access" - then the CLI repo for instance may have @rgee0 and @johnmccabe as having rebase access, so you'd end up with the following for the CLI repo: @alexellis @rgee0 and @johnmccabe without having to specify that @alexellis had access to this feature.

Current Behaviour

Possible, but with duplication and maintenance is required for separate files.

Possible solution

If redirect_url is present, fetch that config file then overlay it with the file being read afterwards.

Move to OpenFaaS golang-http-template - part 2

Expected Behaviour

I would like to move Derek to the OpenFaaS golang-http-template so that the process can stay alive for longer without re-forking. This would allow access tokens etc to be cached in memory to reduce API requests and will increase memory under load.

It is also a step towards #62 (break out SDK) so that Derek can be run on other platforms or by other processes other than the OpenFaaS watchdog to enable wider use.

Current Behaviour

Each request runs in a new process meaning that panic and os.Exit() are fair-game to appear anywhere in the code. This prevents the above, so part of the work is refactoring any exiting and error handling.

Possible Solution

Template:

golang-http via: https://github.com/openfaas-incubator/golang-http-template

The initial work will be moving to the new template signature, this should be minimal, then from there testing that we never call panic/os.Exit.

The current Dockerfile is unnecessary at this point, since it could be replaced by the original Golang template. https://github.com/alexellis/derek/blob/master/Dockerfile

Todo: Migrate namespaces / packages to openfaas/derek

Todo: Migrate namespaces / packages

This would be change to go from alexellis/derek to openfaas/derek.

Allow custom URL via env-var for customer validation

Expected Behaviour

Anyone can host their own Derek and also validate their own customer list

Current Behaviour

The code will validate against our list.

Possible Solution

There is a workaround though - just disable customer validation via the existing env-var flag.

I'd suggest we allow the customer list URL to be supplied via env-var too.

Related #51

Refactoring: Read secrets from OpenFaaS secrets

Right now secrets need to be built into a local/private image or bind-mounted. Derek should read secrets from the OpenFaaS /run/secrets/ folder which happens to be the same on Kubernetes and Swarm alike.

Secrets:

• GitHub symmetrical secret used for checking the HMAC
• Cert / pem file used for authenticating to the GitHub API via OAuth

Research item: use GitHub status API for DCO checking

GitHub has a status/check API that can be used to register our DCO check.

Here's an example:

Checks can help make sure users don't merge PRs when the DCO isn't present.

This should be considered a PoC/research item. If it works out well I will merge so we can adopt it on OpenFaaS.

Suggestion: document the supported features

OK, this is possibly my own fault for missing the forrest for the trees, but I can't seem to find documentation of the config file syntax and especially which features are actually supported. There are a couple of examples, but... is there documentation somewhere that I just didn't see?

Expected Behaviour

An easy to find section in the documentation that tells me more about the syntax of the config file and the supported features.

Current Behaviour

I looked on GitHub, I git-grep-ed through the sources, I couldn't find it - and am very worried that @alexellis will respond to this issue saying: look, there...

Context

A new user of the bot might benefit from easy to find documentation...

Your Environment

• You're using the hosted Derek service

or

• You host your own OpenFaaS cluster with Derek installed

Proposal: allow Derek to apply labels in response to comments

Alex: "Derek apply label skill/beginner"

Derek: Sorry you're not in the MAINTAINERS file.

Derek: Sure
Derek added label "skill/beginner" to the issue

Proposal: Enable changing of issue/PR title

Add Derek set title: This is the new title functionality so that maintainers can painlessly manage imprecise or ambiguous issue titles.

Suggestion: support manipulation of milestones

Derek already supports manipulation of Labels. The GitHub API for Milestones is very similar. Milestones are used to group issues that belong together as a feature or a deliverable. See here for the distinctions: https://guides.github.com/features/issues/

Expected Behaviour

Derek set milestone: 4.8 should add the named milestone to the current issue
Derek remove milestone: 4.8 should accordingly remove the milestone

Current Behaviour

Milestones aren't supported at all

Possible Solution

Add code analogous to the Label handling.

Context

Subsurface is starting to use Milestones to group issues that we want to address for upcoming releases and it would be very useful if more people were able to set/remove milestones from issues, without being Collaborators on the project

Your Environment

• You're using the hosted Derek service

or

• You host your own OpenFaaS cluster with Derek installed

Add support for assigning and unassigning issues/PRs

Expected Behaviour

Derek should be able to assign and unassign issues and PRs, with the target me as a shortcut for the maintainer who issued the request.

Derek assign: me
Derek assign: alexellis
Derek unassign: me
Derek unassign: alexellis

Proposal: Add an autolabels section to DEREK.yml to automatically label issues

Add an autolabels section to DEREK.yml so that any issues raised containing the words within this section are automatically labelled:

e.g.

autolabels:
    - proposal
    - question
    - enhancement

Also add - autolabels to the features section to enable/disable

Introducing

.DEREK.yml feature flags + maintainers list

The .DEREK.yml file should take over the place of the MAINTAINERS file.

This will support roles / actions and mapping users to roles, but initially will look like this:

maintainers:
 - alexellis
 - rgee0
features:
 - dco_check
 - comments

See 2.0 extensions - #22

Encourage clean commit messages

I think Derek can help us with commit messages - as a sort of "linter"

Some may argue a pre-commit hook could do this, but it would have to live in every git repo - Derek can automate some of this.

This post by Chris Beans seems to be well-regarded in the larger community and is also referenced vey the Moby project: https://chris.beams.io/posts/git-commit/

• Always start a commit subject (first line) with a capital letter
• Never exceed 50 chars for the first line of a commit message
• When a commit body is given make sure it wraps to 70 chars max per line

This would be a "feature" and it would be up to the project maintainers as to what they do with the information.

If the rules are invalidated a label could be added with a comment. When the rules are valid the label will be removed. You could get the label more than once but not whilst the "label" is still in place.

Label could be: review/commit-msg

Refactoring for additional feature handling

Awesome project! Was thinking about taking a crack at #17 and wandered how you wanted to handle more features being added in the code? Checks like this one assume only one feature for handling PRs, and this might need to be refactored if more are being added?

Also the code in handlePullRequest may need some refactoring to run through different features if they're enabled / disabled etc...

#17 is just a single addition so can fit into the current model, but just wanted to check on direction before I do anything, or if you think refactoring for potentially more scope later on is the way to go first?

Happy to have a go at either, thanks!

Proposal: Track rate limiting from GitHub API

Context

When authenticated we have 50 requests to the API / hour. When we are authenticated we have 5k per hour +/-.

Idea: track rate-limiting

It's unlikely that we will burn up 5k in an hour on the OpenFaaS org, but larger projects may hit this and this should be observable.

What do we do?
How do we track this?

Support redirection for organizations with multiple project repos

Expected Behaviour

A setting should be made available to .DEREK.yml which means Derek will redirect and pull his config from another location. We should probably enforce some basic validations here and I'm open to suggestions.

Current Behaviour

We maintain separate config files per repo within the organization of openfaas / openfaas-incubator

Possible Solution

Add a tag to the YAML which overrides the behavior to load the current file.

Context

OpenFaaS contributors have required this

Your Environment

• You're using the hosted Derek service

or

• You host your own OpenFaaS cluster with Derek installed