github-pr-guidelines.yml

name: GitHub - PR Contribution Guidelines

on:
  pull_request_target:
    types: [opened, reopened, edited]

jobs:
  # Ensures PR commits were not added via the GitHub Web UI, which typically indicates
  # the contributor hasn't tested their changes in a local development environment.
  no-web-commits:
    name: No Commits on GitHub Web
    runs-on: ubuntu-26.04
    outputs:
      is_allow_listed: ${{ steps.pr_author.outputs.is_allow_listed }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          sparse-checkout: .github/scripts/pr-guidelines
          sparse-checkout-cone-mode: false

      - name: Check if PR author is allow-listed
        id: pr_author
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          # GITHUB_TOKEN does not have the read:org permission needed for this call
          # while CAMPERBOT_NO_TRANSLATE does, since it is a PAT for the camperbot account with read:org scope
          github-token: ${{ secrets.CAMPERBOT_NO_TRANSLATE }}
          script: |
            const fn = require('./.github/scripts/pr-guidelines/check-allow-list.js');
            await fn({ github, context, core });

      - name: Check if commits are made on GitHub Web UI
        id: check-commits
        if: steps.pr_author.outputs.is_allow_listed == 'false' && github.event.action != 'edited'
        env:
          HEAD_REF: ${{ github.head_ref }}
        run: |
          PR_NUMBER=$(jq --raw-output .pull_request.number "$GITHUB_EVENT_PATH")
          COMMITS_URL="https://api.github.com/repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/commits"
          HAS_GITHUB_SIGNED_COMMIT=$(curl --header "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" "$COMMITS_URL" | jq '[.[] | select(.commit.committer.name == "GitHub") | select(.commit.message | test("revert"; "i") | not)] | length > 0')
          # GitHub Codespaces also produces GitHub-signed commits, but Codespaces users
          # work on descriptively named branches. The web editor defaults to patch-N branches.
          IS_PATCH_BRANCH=false
          if [[ "$HEAD_REF" =~ ^patch-[0-9]+$ ]]; then
            IS_PATCH_BRANCH=true
          fi
          if [ "$HAS_GITHUB_SIGNED_COMMIT" = "true" ] && [ "$IS_PATCH_BRANCH" = "true" ]; then
            echo "IS_GITHUB_COMMIT=true" >> $GITHUB_ENV
          fi

      - name: Add comment on PR if commits are made on GitHub Web UI
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        if: steps.pr_author.outputs.is_allow_listed == 'false' && env.IS_GITHUB_COMMIT == 'true' && github.event.action != 'edited'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            core.setFailed("Commits were added via the GitHub Web UI.");
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "Thanks for your pull request.\n\n**Please do not add commits via the GitHub Web UI.**\n\nIt generally means you have yet to test these changes in a development setup or complete any prerequisites. We need you to follow the guides mentioned in the checklist. Please revalidate these changes in a developer environment and confirm how you validated your changes.\n\nHappy contributing!\n\n---\n_**Note:** This message was automatically generated by a bot. If you feel this message is in error or would like help resolving it, feel free to reach us [in our contributor chat](https://discord.gg/PRyKn3Vbay)._"
            });

      - name: Add deprioritized label
        if: failure()
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.rest.issues.addLabels({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              labels: ['deprioritized']
            });

  # Ensures PRs are not opened directly from the contributor's main branch, which makes
  # it hard to keep the PR up to date as the upstream repository progresses.
  # Kept as a standalone job so it does not depend on the web-commit checks.
  no-main-branch:
    name: No PRs from Main Branch
    runs-on: ubuntu-26.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          sparse-checkout: .github/scripts/pr-guidelines
          sparse-checkout-cone-mode: false

      - name: Check if PR author is allow-listed
        id: pr_author
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          # GITHUB_TOKEN does not have the read:org permission needed for this call
          # while CAMPERBOT_NO_TRANSLATE does, since it is a PAT for the camperbot account with read:org scope
          github-token: ${{ secrets.CAMPERBOT_NO_TRANSLATE }}
          script: |
            const fn = require('./.github/scripts/pr-guidelines/check-allow-list.js');
            await fn({ github, context, core });

      - name: Check if PR is opened from the main branch
        id: check-main-branch
        if: steps.pr_author.outputs.is_allow_listed == 'false'
        env:
          HEAD_REF: ${{ github.head_ref }}
        run: |
          if [ "$HEAD_REF" = "main" ]; then
            echo "IS_MAIN_BRANCH=true" >> $GITHUB_ENV
          fi

      - name: Add comment on PR if head branch is main
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        if: steps.pr_author.outputs.is_allow_listed == 'false' && env.IS_MAIN_BRANCH == 'true' && github.event.action != 'edited'
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "Thanks for your pull request.\n\n**We recommend opening pull requests from a dedicated branch rather than your `main` branch.**\n\nUsing a separate branch for each change lets you work on multiple things at the same time without them interfering with one another. Since this PR is opened from your `main` branch, any new commits you push to `main` will be added to this PR while it stays open. After it is merged, you will need to reset your `main` branch as described in the [basic Git workflow guide](https://contribute.freecodecamp.org/basic-git-workflow/) to keep it in sync with the upstream repository.\n\nHappy contributing!\n\n---\n_**Note:** This message was automatically generated by a bot. If you feel this message is in error or would like help resolving it, feel free to reach us [in our contributor chat](https://discord.gg/PRyKn3Vbay)._"
            });

      - name: Fail if head branch is main
        if: steps.pr_author.outputs.is_allow_listed == 'false' && env.IS_MAIN_BRANCH == 'true'
        run: exit 1

      - name: Add deprioritized label
        if: failure()
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.rest.issues.addLabels({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              labels: ['deprioritized']
            });

  # Normalizes PR titles to follow Conventional Commits format, applying fuzzy fixes
  # for common mistakes like typos, missing colons, or incorrect spacing.
  fix-pr-title:
    name: Fix PR Title
    runs-on: ubuntu-26.04
    needs: [no-web-commits, no-main-branch]
    if: needs.no-web-commits.result == 'success' && needs.no-main-branch.result == 'success' && github.event.action != 'edited'
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          sparse-checkout: .github/scripts/pr-guidelines
          sparse-checkout-cone-mode: false

      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fn = require('./.github/scripts/pr-guidelines/fix-pr-title.js');
            await fn({ github, context });

  # Checks that the PR description still contains the required template.
  # The first 3 checkboxes must be ticked ([x] or [X]).
  # The last checkbox (tested locally) is acceptable to leave unticked
  # but removing the entire template is not.
  check-pr-template:
    name: Check PR Template
    runs-on: ubuntu-26.04
    needs: [no-web-commits, no-main-branch]
    if: needs.no-web-commits.result == 'success' && needs.no-main-branch.result == 'success'
    outputs:
      failure_reason: ${{ steps.check.outputs.failure_reason }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          sparse-checkout: .github/scripts/pr-guidelines
          sparse-checkout-cone-mode: false

      - id: check
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fn = require('./.github/scripts/pr-guidelines/check-pr-template.js');
            await fn({ github, context, core, isAllowListed: '${{ needs.no-web-commits.outputs.is_allow_listed }}' });

  # Coordinates reporting: posts a single combined comment when checks fail,
  # or removes the deprioritized label when all checks pass.
  report:
    name: Report
    runs-on: ubuntu-26.04
    needs: [no-web-commits, no-main-branch, check-pr-template]
    if: always() && needs.no-web-commits.result == 'success' && needs.no-main-branch.result == 'success'
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          sparse-checkout: .github/scripts/pr-guidelines
          sparse-checkout-cone-mode: false

      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fn = require('./.github/scripts/pr-guidelines/report-results.js');
            await fn({
              github,
              context,
              templateResult: '${{ needs.check-pr-template.result }}',
              templateReason: '${{ needs.check-pr-template.outputs.failure_reason }}'
            });