GitHub Actions

Land the shared repository setup before making MarginCI a required check. The private alpha includes a workflow that installs the delivered package separately from your application.

Before you install

Use the authorized package and independently verified checksum from your invitation. Check the runtime and npm versions; actions/setup-node may supply a different bundled npm. For committed JavaScript, add your normal application tests, build and source/output consistency check before measurement.

Install the private-alpha workflow

With permission to use the package in private CI, place the verified tarball and SHA256SUMS in vendor/marginci/ inside your private application repository. Do not add the tarball to the application’s dependencies. Public repositories need a separately arranged private delivery route; do not commit the proprietary package publicly.

Copy the template from the tooling installation:

mkdir -p .github/workflows
cp "$HOME/.local/share/marginci/0.3.0-alpha.16/node_modules/marginci/examples/private-alpha-action.yml" .github/workflows/marginci.yml

Review the workflow, checksum and tarball together before supplying credentials. Change the research operation name in both the measurement command and final verifier if your operation has another name. Configure only the provider secrets your operation uses. For a pnpm application, also provision its exact pinned pnpm version on PATH before measurement.

The template uses Ubuntu 24.04, Node.js 24.21.0, read-only repository permissions, pinned actions and a job timeout. It verifies the package checksum and installs the CLI under RUNNER_TEMP with install scripts disabled. The install step writes its bin directory to GITHUB_PATH for later steps. It does not download a missing CLI with npx.

A separate registry-install workflow is available for repositories with an authorized registry package and committed devDependency/lockfile. It is not the manual private-alpha installation path.

Compare the PR’s revisions

The workflow checks out the PR head commit and compares it against github.event.pull_request.base.sha. It fetches full history and does not persist checkout credentials. It runs:

mkdir -p .marginci
marginci doctor research --against "$MARGINCI_BASE_SHA"
marginci test research --against "$MARGINCI_BASE_SHA" --json > .marginci/ci-report.json

The candidate is the PR head, not GitHub’s synthetic merge commit. A missing baseline or shared setup fails before provider work. Each revision uses its own application code and locked dependencies.

Protect credentials and require PASS

The template rejects fork PRs and public-repository artifact storage before checkout or secret-bearing execution. Provider secrets are available only to the measurement step. Same-repository code still needs review: internal contributors and workflow changes must be trusted with those credentials. Add protected environments or approvals if your policy requires them. Never combine pull_request_target, untrusted PR code and secrets.

To test a fork contribution, first review it and move the approved code to a trusted internal branch. Run a new comparison for that branch’s event and commit identities.

Make the result a required check

A failed workflow blocks merging only when an active branch protection rule or ruleset requires the MarginCI check on the target branch. For private repositories, branch protection requires GitHub Pro, GitHub Team, GitHub Enterprise Cloud or GitHub Enterprise Server. Repository branch rulesets require GitHub Pro, GitHub Team or GitHub Enterprise Cloud on GitHub.com. GitHub Free’s public-repository availability does not enable these features in a private repository. Verify feature availability, target branches, enforcement and bypass permissions through your normal repository policy, then verify actual merge blocking. A workflow failure alone does not prove enforcement.

The workflow’s final always() step requires a successful measurement step, a valid schema-2 PASS report, complete workload coverage, exit code 0 and matching base/head identities. It rejects missing, malformed, skipped or non-PASS evidence and receives no provider secrets.

Keep that verifier unconditional. Do not add job conditions or path filters that allow the comparison to be skipped: GitHub can treat skipped or neutral jobs as acceptable required checks. Setup success cannot replace a completed cost comparison. Review changes to the workload and success checks even when the cost result passes.

The private-alpha template does not upload raw logs or reports automatically. Review retained files before adding artifact uploads; see Security and data handling.

What has been tested

Package tests cover installation and result handling with simulated provider responses. Before relying on the check, verify credential delivery, rejection of forked pull requests, and enforcement of the required status check in your repository.