gagoar/use-herald-action

Add documentation for permissions and workflow tokens

gagoar opened this issue · 2 comments

When using the GITHUB_TOKEN provided by workflows the token does not have permission to mention groups within an organization. for this to work. the private repos should have a GitHub app that can allow them to mention groups.

we should describe how to provide that information and what to follow if ppl needs to create their own app.

To expand a little bit here.

the permissions on secrets.GITHUB_TOKEN provided in a workflow is not sufficient to mention users and teams that belong to private organizations. This is often a problem because even tho use-herald-action will post correctly on the comment, Github will not mention the users (will not notify them) due to these permissions.

A solution to this will be issue #58, but in the meantime, a possible workaround is to pass a token from a Github App that has access to these permissions.

A way to do it without too much hassle is like is:

  1. Create a Github App in that your organization controls and can grant access to it.

  2. Find the GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_PRIVATE_KEY for that Github App and save it in secrets under your organization/repository

  3. Provide needed permissions on PR's , comments, isusses (we can expand on this )

  4. add a workflow to your existing use-herald-action that passes the following information

   - id: auth
        uses: jnwng/github-app-installation-token-action@v1
        with:
          appId: ${{ secrets.GITHUB_APP_ID }}
          installationId: ${{ secrets.GITHUB_APP_INSTALLATION_ID }}
          privateKey: ${{ secrets.GITHUB_PRIVATE_KEY }}
   - uses: actions/checkout@master
   - name: Apply herald rules
      uses: gagoar/use-herald-action@v1.4.0
      with:
        GITHUB_TOKEN: ${{ steps.auth.outputs.token }}
        rulesLocation: herald_rules/*.json

some other permission that ppl should know about:
assign: it can only contain 10 users and not teams.

reviewers: teams (in private organizations) will fail silently if it can't apply the team as a reviewer. also, teams field and users are not interchangeable and if a team is listed as a user, GitHub API will reject that silently

As mentioned in #148, there needs to be documentation in the README explaining the permissions issue, and a link to the setup flow.