GitHub Action
git-democracy
Use this GitHub action to add voting to your projects. 🚀
Traditionally, most repositories need some number of approvers to make a change and it's not clear what to do with controversial changes such as with standards changes such as a change to linter formatting.
This GitHub action was created to allow projects to require a vote to pass before letting a pull request be mergeable.
When a Pull Request is made to your repository's main branch, a new comment is posted by the action that shows the status of the vote (which will generally be a not passing vote).
Approvals or Requesting Changes on the Pull Request is the mechanism to cast a vote. Although, only configured voters are counted. Failed votes will list the reasons why the vote failed in the action's error messaging.
When a Pull Request is update, it will clear the vote as the Pull Request reviews are cleared.
This Github action requires the ability to read/write comments on Pull Requests (Issues api).
All potential voters will need to be able to post Pull Request reviews, this should be safe after you have integrated git-democracy
as it will be what blocks merge approvals.
Under Settings
> Actions
> General
(ex: https://github.com/<org>/<repo>/settings/actions
)
Follow documentation here: https://docs.github.com/actions/reference/authentication-in-a-workflow#modifying-the-permissions-for-the-github_token
(Please contribute if you've done this)
Create a new workflow in .github/workflows/
as a new .yaml
file.
name: 'Voting'
on:
pull_request_target:
types: [opened, synchronize, reopened, closed]
jobs:
democracy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Evaluate vote
uses: myyk/git-democracy@v2
The name of the workflow must be Voting
to match the badge that will be
linked to the voting comment.
It's important that the workflow runs as triggered by pull_request_target
and
not pull_request
so that a vote cannot be circumvented by a Pull Request
containing changes to the rules of voting.
It's recommended to set your repository's branch settings to require the voting
as part of the Branch protection rules
by enabling
Require status checks to pass before merging
at a minimum enabling it for your
new workflow. It may need a little time after running the action before the
new workflow is selectable in the UI.
The configurations should be in the workflow definition's folder to get protections from being run with different configurations from a pull requester (with using pull_request_target
trigger).
The default location is to be in the same directory as the action's definition for composite actions. For everything else, the location must be specified manually using the configPath
parameter.
with:
configPath: .github/workflows
The action expects a .voting.yml
defining the rules of voting.
percentageToApprove
is the percentage of weighted votes needed to approve a
vote defined by the number of weighted for votes over the total number of
weighted vote. This number must be above 0 for this action to have any affect.
minVotersRequired
is the minimum number of unique voters need to call the
results of a vote. These voters can be for or against. This number must be above
1 for the action to have any affect.
minVotingWindowMinutes
is the minimum amount of time that must pass after the voting comment is created before any vote can pass.
Example:
---
percentageToApprove: 75
minVotersRequired: 3
minVotingWindowMinutes: 7200
The action expects a .voters.yml
defining the voters and their vote weights.
Each entry should have the format of <github-user>:<voting-weight>
. In a
normal fair election, every voter has would be configured to have a weight of 1.
---
myyk: 1
jienormous: 1
An example of a fully wired up project: https://github.com/myyk/git-democracy-example
Please do not use v1
tag as it is not secure since a pull requester could overwrite your .voters.yml
and .voting.yml
files.
Easy upgrade steps:
- Move your
.voters.yml
and.voting.yml
files into your.github/workflows/
directory somewhere. - Make sure all your voters are also Pull Requesters in your repo/org/account settings.
- Update
uses: myyk/git-democracy@v1
->uses: myyk/git-democracy@v2