# How to Set Up no-mistakes for Fork Contributions on GitHub: A Complete Guide

> Effortlessly set up no-mistakes for GitHub fork contributions. Initialize your local clone to simplify pushes and automate pull requests to the upstream repository.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-07-14

---

**Initialize your local clone with `no-mistakes init --fork-url <your-fork>` to route all pushes to your fork while automatically opening pull requests against the upstream repository.**

`no-mistakes` is a Go-based CLI tool that prevents accidental data loss by orchestrating a background daemon, CI pipelines, and intelligent agents. When contributing to open-source projects via a fork, you must configure the tool to distinguish between the upstream repository and your personal fork to ensure branches push to the correct remote and PRs target the proper destination.

## Understanding the Fork Routing Architecture

The **fork-routing** logic documented in [`AGENTS.md`](https://github.com/kunchenguid/no-mistakes/blob/main/AGENTS.md) separates your workspace from the upstream project by maintaining two distinct remote URLs. At the core of this system is the `Repo.PushURL()` method (implemented in [`internal/git/repo.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/repo.go)), which dynamically selects the appropriate remote during Git operations. When you initialize the repository with a fork URL, the daemon intercepts all push commands and redirects them to your fork while preserving the upstream repository as the PR target.

## Step-by-Step Setup for Fork Contributions

### 1. Initialize the Repository with Your Fork URL

Run the initialization command once per clone to record both the upstream origin and your fork:

```bash
no-mistakes init --fork-url https://github.com/<your-username>/no-mistakes.git

```

The `init` command parses the `--fork-url` flag (see the flag handling at lines 36–37 of [`internal/cli/init.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/init.go)) and validates that the URL is non-empty, throwing `init: --fork-url must not be empty` if omitted. This value is persisted in the repository’s configuration file alongside other settings.

### 2. Verify the Fork Configuration

After initialization, the CLI stores your fork URL in the repository configuration. The daemon reads this value on every subsequent operation to determine remote routing. You do not need to manually configure Git remotes; the tool abstracts this through the `Repo.PushURL()` abstraction layer.

### 3. Push Branches to Your Fork

Create your feature branch and push using the `axi` command:

```bash
git checkout -b my-feature
git add .
git commit -m "Add new feature"
no-mistakes axi push

```

The `axi push` command invokes `Repo.PushURL()` to direct the push to your fork URL rather than the upstream origin. This prevents accidental writes to the main repository while ensuring your changes are available on your fork for PR creation.

### 4. Open Pull Requests Against Upstream

Create the pull request using the dedicated PR command:

```bash
no-mistakes axi pr

```

This command constructs the `gh pr create` invocation with `--head <fork-owner>:<branch>` while keeping `--repo` pointed at the upstream repository. The result is a PR opened against the upstream project that references your fork’s branch as the source, exactly as required by the **Fork Routing** section of [`AGENTS.md`](https://github.com/kunchenguid/no-mistakes/blob/main/AGENTS.md).

## Safety Guarantees and Validation

The fork-routing implementation includes multiple safeguards to prevent accidental pushes to upstream. The code never attempts to push directly to the origin repository when a fork URL is configured. All push operations are mediated by `Repo.PushURL()`, which abstracts the remote selection logic and prevents force-pushes to the upstream repository. The integration tests in [`internal/e2e/fork_routing_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/e2e/fork_routing_test.go) verify that the `init --fork-url` configuration correctly routes both pushes and PRs throughout the entire workflow.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`internal/cli/init.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/init.go) | Parses `--fork-url` and validates the fork remote configuration (lines 36–37). |
| [`internal/git/repo.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/repo.go) | Contains `Repo.PushURL()` which determines the correct remote for Git push operations. |
| [`internal/scm/gitlab/gitlab.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/scm/gitlab/gitlab.go) | Implements remote-specific handling logic (GitHub uses similar patterns). |
| [`internal/e2e/fork_routing_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/e2e/fork_routing_test.go) | Integration tests verifying fork routing and PR creation against upstream. |
| [`AGENTS.md`](https://github.com/kunchenguid/no-mistakes/blob/main/AGENTS.md) | High-level design documentation for the fork routing and safety guarantees. |

## Summary

- **Initialize once** with `no-mistakes init --fork-url <url>` to record your fork destination (validated in [`internal/cli/init.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/init.go)).
- **Push safely** using `no-mistakes axi push`, which routes branches to your fork via `Repo.PushURL()`.
- **Target upstream** automatically with `no-mistakes axi pr`, creating PRs against the origin repository while using your fork as the head.
- **Stay protected** by the built-in validation that prevents direct pushes to upstream when a fork URL is configured.

## Frequently Asked Questions

### What happens if I don't specify --fork-url during init?

Without the `--fork-url` flag, the CLI defaults to treating the origin remote as both the source and target for all operations. This means `no-mistakes axi push` will attempt to write directly to the upstream repository, which will fail if you lack write permissions or could accidentally modify the main branch if you do have access.

### Can I change the fork URL after initialization?

Yes, you can re-run `no-mistakes init --fork-url <new-url>` to update the configuration. The validation logic in [`internal/cli/init.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/init.go) will overwrite the existing fork URL in the repository settings, and subsequent `axi` commands will immediately route pushes to the new remote without requiring a fresh clone.

### How does no-mistakes prevent accidental pushes to upstream?

The tool uses the `Repo.PushURL()` abstraction (implemented in [`internal/git/repo.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/repo.go)) to select remotes. When a fork URL is present in the configuration, this method always returns the fork URL for push operations, ensuring the Git commands never target the upstream origin. This is enforced by the daemon and validated through the test suite in [`internal/e2e/fork_routing_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/e2e/fork_routing_test.go).

### Does fork routing work with GitLab or other Git providers?

Yes, the fork routing logic is provider-agnostic. While the examples reference GitHub, the underlying implementation in [`internal/scm/gitlab/gitlab.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/scm/gitlab/gitlab.go) and related packages handles remote URL construction for multiple providers. The `--fork-url` flag accepts any valid Git URL, and the PR creation logic adapts to the specific SCM provider detected in the repository configuration.