Repository files navigation

Use this GitHub action to add voting to your projects. 🚀

Traditionally, most repositories need some number of approvers to make a changeand it's not clear what to do with controversial changes such as with standardschanges such as a change to linter formatting.

This GitHub action was created to allow projects to require a vote to passbefore letting a pull request be mergeable.

When a Pull Request is made to your repository's main branch, a new comment isposted 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, onlyconfigured voters are counted. Failed votes will list the reasons why the vote failed inthe 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 integratedgit-democracy as it will be what blocks merge approvals.

UnderSettings >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@v4      - name: Evaluate vote        uses: myyk/git-democracy@v2

The name of the workflow must beVoting to match the badge that will belinked to the voting comment.

It's important that the workflow runs as triggered bypull_request_target andnotpull_request so that a vote cannot be circumvented by a Pull Requestcontaining changes to the rules of voting.

It's recommended to set your repository's branch settings to require the votingas part of theBranch protection rules by enablingRequire status checks to pass before merging at a minimum enabling it for yournew workflow. It may need a little time after running the action before thenew 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 usingpull_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 theconfigPath 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 avote defined by the number of weighted for votes over the total number ofweighted 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 theresults of a vote. These voters can be for or against. This number must be above1 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: 75minVotersRequired: 3minVotingWindowMinutes: 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 anormal fair election, every voter has would be configured to have a weight of 1.

---myyk: 1jienormous: 1

An example of a fully wired up project:https://github.com/myyk/git-democracy-example

Please do not usev1 tag as it is not secure since a pull requester could overwrite your.voters.yml and.voting.yml files.

Easy upgrade steps:

1. Move your.voters.yml and.voting.yml files into your.github/workflows/ directory somewhere.
2. Make sure all your voters are also Pull Requesters in your repo/org/account settings.
3. Updateuses: myyk/git-democracy@v1 ->uses: myyk/git-democracy@v2