Skip to content

docs: README example needs secure defaults (permissions scope, action SHA pin, glob paths) #1

Closed

Description

@andriishin

Context. Across three migration PRs (bludit#1706, Artalk#1124, ai-brain-tool#42), CodeRabbit flagged the same three workflow issues every time:

  1. Top-level permissions: contents: write — too broad. Drift-check job only needs read. Should be scoped per-job.
  2. uses: nanolaba/nrg-action@v1 — floating tag is a supply-chain concern. Should be pinned to commit SHA (@9fae0216ed0c828f520e555912776ca624d84fb5 # v1).
  3. Hardcoded list of generated README paths in the commit step — misses any future language added to nrg.languages. Should use a glob with git pathspec exclude.

The reason this keeps happening: the canonical example in this repo's README and in past migration PRs doesn't show the secure pattern. Every new adopter trips the same CodeRabbit findings, looks bad on their PR, and we (or they) have to push a hardening commit.

Proposal. Rewrite the example workflow in the README so it ships secure-by-default:

name: Regenerate READMEs
on:
  push:
    branches: [main]
    paths:
      - 'README.src.md'
      - '.github/workflows/nrg.yml'
  pull_request:
    paths:
      - 'README.src.md'
      - 'README.md'
      - 'README.*.md'
      - '.github/workflows/nrg.yml'
permissions:
  contents: read
jobs:
  regenerate:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          token: \${{ secrets.GITHUB_TOKEN }}
      - uses: nanolaba/nrg-action@<COMMIT-SHA>  # v1
        with:
          file: README.src.md
          nrg-version: '1.2'
      - name: Commit regenerated READMEs
        run: |
          paths=("README.md" "README.*.md" ":(exclude)README.src.md")
          status="\$(git status --porcelain -- "\${paths[@]}")"
          if [ -n "\$status" ]; then
            changed=\$(printf '%s\n' "\$status" | sed 's/^...//' | sed 's/^/  - /')
            git config user.name "github-actions[bot]"
            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
            git add -A -- "\${paths[@]}"
            git commit -m "docs: regenerate READMEs from README.src.md" \
              -m \$'Files updated:\n'"\$changed"
            git push
          fi

  drift-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nanolaba/nrg-action@<COMMIT-SHA>  # v1
        with:
          file: README.src.md
          mode: check
          nrg-version: '1.2'

The <COMMIT-SHA> placeholder needs README to call out the canonical SHA per release tag (e.g. via a "current canonical SHA" line, or a release-time job that updates the README example automatically).

Optional follow-up. Add a section "Hardening" or "Security" right under the example that explains the three deviations from a naive scaffold, so a reader who copy-pastes can leave the secure shape intact instead of "simplifying" it back to the broken pattern.

Why now. The action's discoverability flywheel is migration PRs → CodeRabbit reviews on those PRs → 1st impression for every new adopter. If the canonical example trips the bot every time, the pitch is undermined right at the moment the maintainer is deciding whether to merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions