Skip to content

github-action-usage.md

Latest commit

 

History

History
181 lines (145 loc) · 7.84 KB

github-action-usage.md

File metadata and controls

181 lines (145 loc) · 7.84 KB
Raw

PatchGate GitHub Action Usage Guide

PatchGate contains a local/shadow GitHub Action candidate. It is not yet a released Marketplace action or a proven public v0.1 distribution.

For a real external shadow installation, use the G4 shadow-installation runbook. For release validation, upgrade, downgrade and rollback, use the beta release and rollback guide after the documented gates have been reviewed.

1. Quick Start: Shadow Mode (Recommended for Initial Setup)

In Shadow Mode, PatchGate observes only (fail-on: never). It evaluates the PR, writes the ContributionReceipt, and can post a Check Run without blocking merge. Pin v0.1.0-beta.5 for discovery, but install the immutable source commit 34d998bbd59fa09dd9081e24f22abe812f97fbab. This is not production and not a v0.1 claim.

The Action reads GitHub metadata through the API. Do not check out pull-request code in this workflow. github.token cannot be granted the Administration permission, so branch-protection/Rulesets snapshots are incomplete with GITHUB_TOKEN and fail closed. A complete native-control snapshot needs a PAT or GitHub App token with administration: read.

Create .github/workflows/patchgate-shadow.yml:

name: PatchGate Shadow Evaluation

on:
  pull_request_target:
    types: [opened, synchronize, reopened]
  merge_group:
    types: [checks_requested]

concurrency:
  group: patchgate-shadow-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  checks: write
  pull-requests: read
  contents: read
  actions: read

jobs:
  evaluate:
    name: Review-Readiness Shadow Gate
    runs-on: ubuntu-latest
    steps:
      # Commit this file on the default branch first; pull_request_target
      # only runs workflows already on that branch.
      # github.token cannot read Administration, so native Rulesets /
      # branch-protection snapshots fail closed (correct). A PAT/App token
      # with administration:read is required for a complete native-control
      # snapshot. The Check Run output shows the full tested SHA and its
      # binding to the PR head; a stale event is rejected before evaluation.
      # The public beta posts a Check Run for successful evaluations;
      # snapshot-rejection Check Runs are included in the public beta.
      # Release identity before resolving the immutable commit:
      # uses: daichunghy/patchgate@v0.1.0-beta.5
      - name: Run PatchGate Shadow Gate
        uses: daichunghy/patchgate@34d998bbd59fa09dd9081e24f22abe812f97fbab # v0.1.0-beta.5
        with:
          fail-on: never
          create-check-run: true
          github-token: ${{ github.token }}

2. Hardened Enforcement Mode (do not copy yet)

This is a later step after a consented shadow install, not a first-paste workflow. It is still not production or a v0.1 claim.

      - name: Run PatchGate Enforcing Gate
        uses: daichunghy/patchgate@34d998bbd59fa09dd9081e24f22abe812f97fbab # v0.1.0-beta.5
        with:
          fail-on: blocked
          create-check-run: true
          github-token: ${{ github.token }}

2a. Developing PatchGate itself

This section is only for this repository's own shadow workflow. External consumers should use the tagged Action above, not uses: ./ after npm ci.

      - name: Checkout trusted base repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          ref: ${{ github.base_ref }}
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: 20.x
          cache: 'npm'

      - name: Install dependencies & Build
        run: |
          npm ci
          npm run build

      - name: Run PatchGate Shadow Gate
        uses: ./
        with:
          fail-on: never
          create-check-run: true
          github-token: ${{ github.token }}

3. Action Inputs & Outputs

Inputs

Input Description Default Allowed Values
fail-on Status level causing step failure blocked never, blocked, human_review_required, evidence_missing, policy_ambiguous
github-token GitHub token for reading metadata; checks: write is also required when create-check-run: true ${{ github.token }} String
create-check-run Post idempotent GitHub Check Run true true, false
check-name Title of the GitHub Check Run PatchGate Review Gate String
report-path Output path for ContributionReceipt patchgate-receipt.json Path string

Outputs

Output Description
status Final status (ready_for_review, blocked, human_review_required, evidence_missing, policy_ambiguous)
receipt-path Local filesystem path to the saved ContributionReceipt JSON file
receipt-digest SHA-256 canonical digest of the evaluation receipt
decision-input-digest SHA-256 canonical digest of the normalized input snapshot
summary-markdown Formatted Markdown summary suitable for step summaries or issue comments
target-kind Evaluation target kind (head, merge, or merge_group)
tested-sha Exact commit SHA evaluated and used as the Check Run head_sha
head-sha Exact pull-request head SHA recorded in the evaluation

Commit-bound evidence and QAOnFire interoperability

For pull_request and pull_request_target, the Action binds the live API snapshot to github.event.pull_request.head.sha. If the pull request advanced between event delivery and API collection, PatchGate returns a non-evaluable GITHUB_TARGET_CHANGED result and does not publish a green result for the newer revision. A successful Check Run uses the receipt's exact testedSha as its API head_sha, and the summary displays the full testedSha and headSha.

Keep check-name stable. Do not append a SHA to it: the required-check identity is a repository configuration key, while the commit binding belongs in the Check Run head_sha and output.

QAOnFire currently describes its GitHub App as posting a QA report as a pull- request comment. PatchGate treats that comment as context, not verified check evidence. The public GitHub App metadata currently lists App ID 3791637, pull_request and issue_comment events, and no checks:write permission, so it cannot currently publish a Check Run for a required-check rule. To make a QAOnFire result satisfy that rule, the App would need to publish a Check Run with the actual target SHA and an identifiable source App; the repository could then configure that App explicitly in patchgate.yml.

4. Security Architecture & Boundary Rules

  1. Hostile Boundary Isolation: PatchGate never executes contributor code inside the decision lane.
  2. Base Revision Authority: Policy rules and CODEOWNERS are exclusively loaded from the trusted base commit (baseSha), preventing pull requests from relaxing their own rules.
  3. Minimal Permissions: The action requires contents: read and pull-requests: read; add checks: write only when check runs are enabled. Native-control boundary: the GITHUB_TOKEN cannot be granted the Administration permission (the workflow permissions syntax has no administration key), so branch-protection/Rulesets visibility is incomplete with github.token and the evaluation fails closed with GITHUB_PROVENANCE_AMBIGUOUS. A complete snapshot requires a PAT or GitHub App token with administration: read; see the live smoke findings.
  4. Merge-group boundary: merge_group is recognized and returns an explicit evidence_missing result until authenticated multi-PR membership is supported.