Skip to content

3. CI Usage Guide

Jump to bottom
Semenov Dmitrii edited this page Feb 17, 2026 · 1 revision

This page describes a conservative, CI-friendly workflow for using GDShrapt in automated pipelines.

GDShrapt’s default behavior is safe-by-default: rename --apply applies only Strict edits, and string-based contracts require explicit opt-in.

Principles

  1. Fail fast on analysis regressions
  2. Never apply unproven edits automatically
  3. Make rename operations auditable via diffs
  4. Keep CI output stable and machine-readable when needed

Recommended CI steps

1) Analyze (lint + validate)

Run full diagnostics on the project:

gdshrapt analyze .

If you want CI to fail on warnings too:

gdshrapt analyze . --fail-on warning

2) Check (exit-code oriented)

If you need a fast, CI-oriented gate:

gdshrapt check .

Use --fail-on warning when you want warnings to fail the build.

3) Optional: Validate or Lint separately

gdshrapt validate .
gdshrapt lint .

CI-safe rename workflows

A) CI preview-only (recommended default)

In CI, you usually want to detect what would change, not apply it automatically.

gdshrapt rename <old> <new> --diff

If the command finds candidates, you can:

  • post the diff as an artifact
  • require a maintainer to run --apply locally

B) Controlled rename application (strict-only)

If you have a dedicated refactor job (not every PR), you can allow Strict-only application:

gdshrapt rename <old> <new> --apply

Recommended additions:

  • keep a clean working tree check before/after
  • commit changes automatically in a bot branch, not on PR branches directly

C) Contract strings are an explicit decision

Contract strings are preview-only unless you opt in:

gdshrapt rename <old> <new> --apply --include-contract-strings

Only enable this in CI if you have a clear policy that string-based contracts are safe to change for your project.

Make output deterministic

To reduce noisy diffs in CI:

  • run with stable log level (avoid --verbose unless debugging)
  • set --color never for clean logs
  • constrain concurrency if your environment needs reproducibility

Examples:

gdshrapt analyze . --color never --log-level info
gdshrapt rename <old> <new> --diff --color never --log-level info

If necessary:

gdshrapt analyze . --max-parallelism 0

Use JSON output for tooling

When you want to parse results:

gdshrapt analyze . --format json
gdshrapt rename <old> <new> --diff --format json
gdshrapt find-refs <symbol> -p . --format json

Use this for:

  • PR annotations
  • dashboards
  • regressions/baselines

Suggested pipeline patterns

Pull request pipeline

  • gdshrapt check . (fast gate)
  • gdshrapt analyze . --fail-on warning (stricter gate if desired)
  • No automatic rename application

Nightly pipeline

  • gdshrapt analyze . --format json (trend analysis)
  • optional: gdshrapt type-coverage .
  • optional: gdshrapt metrics .

Refactor pipeline (manual trigger)

  • gdshrapt rename ... --diff --explain
  • human review
  • gdshrapt rename ... --apply (Strict only)
  • optional: --include-contract-strings only when approved

Guardrails

Ensure working tree is clean

Before applying in automation, ensure no uncommitted changes exist. GDShrapt will modify files when --apply is used, so you should treat it like a codegen step.

Keep rename scope small

During early adoption, prefer scoping:

gdshrapt rename <old> <new> --file path/to/file.gd --diff --explain

Then scale up.

Troubleshooting

The diff is too large

  • scope by file
  • rename incrementally
  • avoid contract strings unless necessary

The tool times out on large projects

Increase per-file timeout:

gdshrapt analyze . --timeout-seconds 60

Or reduce parallelism if your CI runners are constrained.

Notes on safety

  • --apply applies Strict edits only.
  • Contract strings are preview-only unless --include-contract-strings is set.
  • Potential/NameMatch are intended for manual review, not automation.

Clone this wiki locally