githubnext / githubnext/crane

Make protected-file policy configurable and consistent for migration branches

Open
#7 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
10
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Background

During the githubnext/apm Python-to-Go migration, Crane repeatedly needed to touch files that are commonly protected: `go.mod`, `go.sum`, workflow files, and other project configuration. With protected files set to `fallback-to-issue`, Crane could describe work in an issue but not push the actual migration commit. That caused false progress and stalled PR updates.

APM locally changed the Crane workflow so `create-pull-request` uses `protected-files: allowed`. The upstream lesson is broader: code migration frequently requires manifest, lockfile, or workflow changes, so protected-file behavior must be explicit, configurable, and consistent across both creating the PR and pushing later iteration commits.

## Problem

The default upstream Crane workflow has `create-pull-request` protected files set to `fallback-to-issue`, while `push-to-pull-request-branch` also has its own protected-file behavior from safe outputs. This can create surprising behavior:

- First accepted iteration can fail to create a useful PR if protected files are touched.
- Later iterations can fail to push to the existing migration branch.
- Crane may write fallback issues that look like progress but do not update the PR branch.
- Migrations involving Go, Node, Python, Java, or Rust often need dependency manifest and lockfile edits.

For a migration tool, touching manifest and lock files is often not exceptional. It is part of the migration.

## Proposed implementation

Make protected-file policy an explicit Crane installation or workflow configuration choice.

Possible design:

1. Add an installer prompt in `install.md`:
- Strict: protected files fall back to issue for maximum safety.
- Migration-friendly: protected files are allowed on Crane migration branches.
- Custom: user provides an allowlist or policy.

2. Apply the selected policy consistently to both:
- `create-pull-request`
- `push-to-pull-request-branch`

3. Document when to use each mode:
- Use strict for repositories where agents must never touch manifests or workflow files without human intervention.
- Use migration-friendly when the migration target requires dependency, lockfile, build, or workflow updates.

4. If a protected-file fallback still happens, Crane should treat it as blocked or incomplete, not as an accepted migration iteration. It should tell the maintainer what policy or allowlist needs to change.

5. Consider per-migration override support in migration frontmatter, for example:

```yaml
protected-files-policy: allowed
```

or

```yaml
protected-files-policy: fallback-to-issue
```

## Suggested test coverage

- Prompt or installer tests that verify the protected-file policy is described.
- Workflow prompt test that verifies the policy applies to both PR creation and PR branch pushes.
- If implemented in installer code, test that the selected policy is written into `workflows/crane.md` before `gh aw compile`.

## Acceptance criteria

- A repository owner can choose strict or migration-friendly protected-file behavior during installation.
- The chosen behavior is applied consistently for initial PR creation and later PR updates.
- Crane does not mark protected-file fallback output as a successful accepted iteration unless a commit actually reached the migration branch.
- Documentation explains why migrations may need to touch manifest and lock files.

## Provenance

This came from githubnext/apm, where the Python-to-Go migration needed dependency and workflow changes and protected-file fallback prevented Crane from generating new PR commits.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.