Home / Guides / Workflow Guide

Workflow Guide

Create a feature branch, make changes, open a PR, get reviews, and merge.

Beginner

Workflow Overview

The CodeAnvil workflow follows these steps:

📋 Quick Reference

Create branch → Branch off from main
Make changes → Commit your work
Push & create PR → anvil pr create
Review → Teammates review and approve
Merge → anvil pr merge

Key Concepts

Squash Workflow: PRs are squashed into a single commit for clean history
Signed Reviews: Approvals are GPG-signed and stored as git notes
Branch Protection: Rules enforce required reviews before merging

Create a Feature Branch

Start by creating a branch for your changes:

bash

# Make sure you're on main and up to date
git checkout main
git pull origin main

# Create a new feature branch
git checkout -b feature/add-user-auth

# Make your changes
# ... edit files ...

# Stage and commit
git add .
git commit -m "Add user authentication"

# Push to remote
git push -u origin feature/add-user-auth

Branch Naming Conventions

Use descriptive branch names with prefixes:

Prefix	Use Case	Example
`feature/`	New features	`feature/add-login`
`fix/`	Bug fixes	`fix/null-pointer`
`refactor/`	Code refactoring	`refactor/auth-module`
`docs/`	Documentation	`docs/api-reference`

Create a Pull Request

Once your branch is pushed, create a pull request:

bash

# Create PR from current branch to main
anvil pr create

# Specify target branch
anvil pr create --target develop

What Happens When You Create a PR?

Squash: Your branch commits are squashed into a single commit
Sign: The commit is signed with your GPG key
Store: PR metadata is stored as a git note
Notify: Reviewers are notified (based on branch protection rules)

⚠️ Squash Workflow

CodeAnvil uses a squash workflow — all commits on your feature branch are combined into a single commit. This keeps the main branch history clean and makes it easy to revert entire features if needed.

After Creating the PR

Note the commit hash from the output. You'll use it for all PR operations:

bash

# Example output:
PR created successfully!
Commit hash: a1b2c3d4
Target branch: main

# Use the commit hash for all operations:
anvil pr status a1b2c3d4
anvil pr approve a1b2c3d4
anvil pr merge a1b2c3d4

Review Process

CodeAnvil uses signed code reviews stored as git notes.

For Reviewers: Fetch and Review

Fetch the PR

bash

# Fetch the PR commit
anvil pr fetch a1b2c3d4

# This downloads the commit to your local repo

Review the Changes

bash

# View the commit diff
git show a1b2c3d4

# Or checkout the commit to test
git checkout a1b2c3d4

# Run tests, build, etc.
npm test

# Return to your branch when done
git checkout -

Approve or Reject

bash

# Approve the PR
anvil pr approve a1b2c3d4

# Reject with a reason
anvil pr reject a1b2c3d4 "Security issue: API key exposed in config"

For Authors: Check Status

bash

# Check PR status
anvil pr status a1b2c3d4

# Example output:
PR Status: Open
Commit: a1b2c3d4
Target: main
Approvals: 1/2 required
Mergeable: No (waiting for approvals)

Signatures:
  ✓ alice@example.com approved at 2024-01-15 10:30 UTC

Review Notifications

When a PR is created, all users with write access to the repository receive a notification (via email, if configured). The notification includes:

PR details (branch, commit, author)
Commands to fetch and review
AI review summary (if enabled)
Build status (if builds are configured)

Merge the Pull Request

Once the PR has the required approvals, it can be merged:

bash

# Check if mergeable
anvil pr status a1b2c3d4

# If mergeable, merge it
anvil pr merge a1b2c3d4

# Pull the merged changes
git checkout main
git pull origin main

When Can a PR Be Merged?

A PR can only be merged when:

✅ It has the required number of approvals (based on branch protection)
✅ All builds have passed (if builds are configured)
✅ No rejections are active
✅ The commit is signed

🚫 Cannot Merge?

If pr merge fails, check the status:

bash

anvil pr status a1b2c3d4

# Common issues:
# - "Waiting for approvals" → Need more reviews
# - "Build failed" → Fix build issues first
# - "Rejected by reviewer" → Address feedback

After Merging

The squashed commit is merged into the target branch
The PR status is updated to "Merged"
The author receives a notification
The feature branch can be deleted

bash

# Clean up the feature branch (optional)
git branch -d feature/add-user-auth
git push origin --delete feature/add-user-auth

Troubleshooting

PR Creation Fails

Common Causes

Branch not pushed: Run git push -u origin branch-name
No commits: Make sure you have commits on the branch
Already exists: A PR may already exist for this commit

Approval Not Counted

Common Causes

Wrong commit hash: Make sure you're approving the correct commit
No write access: Reviewer needs write access to the repository
Already approved: Each person can only approve once

Cannot Merge

Common Causes

Not enough approvals: Check anvil pr status
Build failed: Fix build issues and push new commit
Blocked by protection rules: Check branch protection settings

Complete Example

Here's a complete workflow from start to finish:

bash

# === DEVELOPER (Author) ===

# Start from main
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/new-api-endpoint

# Make changes and commit
git add src/api.rs
git commit -m "Add /users endpoint"
git push -u origin feature/new-api-endpoint

# Create PR
anvil pr create
# Output: PR created with commit hash: abc1234

# === REVIEWER ===

# Fetch and review
anvil pr fetch abc1234
git checkout abc1234
cargo test  # Run tests

# Approve
anvil pr approve abc1234

# === DEVELOPER (Author) ===

# Check status
anvil pr status abc1234
# Output: Mergeable: Yes

# Merge
anvil pr merge abc1234

# Update local
git checkout main
git pull origin main

What's Next?

📦 Repositories

Manage access control, visibility, and team members.

🛡️ Branch Protection

Configure required reviews and build checks.

🤖 Build Agents

Set up CI/CD on your infrastructure.