EasyP

GitHub Actions

Verify v1 dependency locks, lint schemas, compare a Git baseline, and check generated output in CI.

Run dependency verification, linting, breaking checks, and generation as separate steps so failures identify the stage that needs attention.

Prerequisites and Toolchain

This example assumes a root protobuf.mod and committed protobuf.lock, a root easyp.yaml, schemas in proto, and a root easyp.gen.yaml writing to tracked files under gen.

The workflow uses a prepared self-hosted Linux runner with the custom label easyp-v1. Assign that label only after provisioning your chosen v1-capable EasyP binary and required local plugins on PATH. For a hosted runner, supply your project's pinned toolchain setup before the EasyP steps. The example does not assume a particular published v1 release artifact.

Local and bundled plugins cannot use a YAML version pin; their versions are controlled by the installed executables and EasyP binary. Remote plugins require a separate pinned semantic version in easyp.gen.yaml.

Pull Request Workflow

name: protobuf-ci

on:
  pull_request:

permissions:
  contents: read

jobs:
  verify:
    runs-on: [self-hosted, linux, x64, easyp-v1]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Verify toolchain
        run: easyp --version

      - name: Verify locked dependencies
        run: easyp mod download

      - name: Lint schemas
        run: easyp lint --path proto

      - name: Check compatibility
        env:
          BASE_REF: ${{ github.event.pull_request.base.sha }}
        run: easyp breaking --path proto --against "$BASE_REF"

      - name: Generate code
        run: easyp generate --project .

      - name: Check committed generated files
        run: |
          git diff --exit-code -- gen
          test -z "$(git ls-files --others --exclude-standard -- gen)"

The final step detects tracked changes and new untracked files under gen. Adapt the paths for your project; ignored generated files are outside this check. Also run your normal consumer tests after generation.

Lint and Breaking Policies

A simple root easyp.yaml is:

version: v1
linters:
  default: STANDARD
breaking:
  baseline: git:main
  categories: [FILE]
  ignore_unstable: false
  ignore: [proto/experimental]

The workflow's explicit --against overrides this baseline with the PR base SHA. Use a ref directly, without git-ref= or git: in the flag. Branches, lightweight and annotated tags, full SHAs, and locally resolvable Git revisions are supported; the required refs and objects must exist locally. A bare branch name wins over an identically named tag.

For a release comparison, select an existing release tag explicitly:

easyp breaking --path proto --against refs/tags/v1.2.0

Choose the intended previous release rather than assuming tag creation order defines compatibility history. Each revision uses its own module manifests, locks, and dependencies, so a breaking check can fetch dependencies beyond those needed by the current checkout.

FILE is the only supported additional category. ignore_unstable works for the supported package suffixes. Ignore paths are relative to the policy file defining the breaking section: here proto/experimental is relative to the root policy. Nested sections replace whole sections; extends explicitly loads a section base from a local file or an existing locked module.

Selecting Generation Projects

With backend and frontend generator files, use:

easyp generate --project ./backend --project ./frontend

Use easyp generate --all for explicit recursive selection. A plain easyp generate selects the nearest enclosing generator file. --project and --all cannot be combined.

To split generation into matrix jobs, set the matrix to project directories and pass the selected directory to --project. Each job needs the relevant plugins and output checks; language names alone do not select a generation configuration.

Dependency Cache and Private Sources

Dependencies belong in protobuf.mod, with resolved commits and hashes in protobuf.lock. easyp mod download verifies that lock without updating it. Do dependency updates in a reviewed change before the verification job.

EasyP storage defaults to ~/.easyp and can be relocated with EASYPPATH. If you cache it, include the OS, EasyP toolchain version, and relevant lockfile hashes in the cache key. A restored cache is an optimization; dependency verification still runs.

For private dependencies, provision the Git authentication required by your sources before the dependency step. Keep credentials in the runner's approved secret mechanism and out of logs. A local replacement does not eliminate downloads unless the entire dependency graph is local or already verified in cache; remote plugins still need the network. tidy and update reject active local replacements and are not read-only verification commands.

Troubleshooting

SymptomCheck
Baseline cannot be resolvedFetch the intended ref and its objects; use full history or an explicit fetch.
Unknown policy field or ruleMatch configuration to the installed v1 binary and supported schema.
Plugin is missing or output differsVerify the executable selected from PATH and the pinned toolchain.
Dependency verification failsCheck the committed manifest, lock, source access, and reported hash mismatch.
Generated-output check failsRegenerate with the same project selection and toolchain, review the diff, and commit intended changes.

For diagnostics, record easyp --version, the failing command, and the relevant Git ref. See breaking checks in CI and build reproducibility.

On this page