This tutorial walks you through your first day with Kizuna, from creating an account to merging your first pull request. By the end, you'll understand the core workflow.

Prerequisites

• A running self-hosted Kizuna instance (there is no hosted cloud)
• Jujutsu (jj) installed (or Git — both work)
• Optionally, the Kizuna CLI (kz)

Step 1: Create Your Account

There is no public sign-up. Production registration is closed unless an operator sets KIZUNA_REGISTRATION=open. The operator creates the first account with KizunaCore.Release.create_admin/3, then you sign in at your instance URL (for example https://kizuna.example.com).

Step 2: Create or Join an Organization

Organizations are the top-level container for repositories and teams.

Create a New Organization

1. Click your avatar in the top-right corner
2. Select New Organization
3. Enter:
   • Name: my-team (URL-safe, lowercase)
   • Display Name: "My Team"
   • Visibility: Private (recommended for teams)
4. Click Create

Join an Existing Organization

Inviting members is not available yet. Another account has to be created by an operator with create_admin.

Step 3: Create Your First Repository

1. From your organization page, click New Repository
2. Fill in:
   • Name: hello-kizuna
   • Description: "Learning the Kizuna workflow"
   • Visibility: Private
   • Initialize with README: Check this box
3. Click Create Repository

You'll land on the repository page showing the default main branch with your README.

Step 4: Clone the Repository

With Jujutsu (Recommended)

jj git clone https://kizuna.yourcompany.com/my-team/hello-kizuna
cd hello-kizuna

With Git

git clone https://kizuna.yourcompany.com/my-team/hello-kizuna
cd hello-kizuna

With the CLI

# Coming soon
kz repo clone my-team/hello-kizuna

Step 5: Make Your First Change

With Jujutsu

Jujutsu has no staging area — every edit is automatically part of the working-copy commit:

# Create a new file
cat > app.js << 'EOF'
function greet(name) {
  return `Hello, ${name}! Welcome to Kizuna.`;
}

console.log(greet("World"));
EOF

# See what jj tracked automatically
jj status

# Describe your change
jj describe -m "Add greeting application"

# View the log
jj log

With Git

git checkout -b feature/greeting

cat > app.js << 'EOF'
function greet(name) {
  return `Hello, ${name}! Welcome to Kizuna.`;
}

console.log(greet("World"));
EOF

git add app.js
git commit -m "Add greeting application"

Step 6: Push Your Change

With Jujutsu

# Push creates a remote bookmark (branch) automatically
jj git push

With Git

git push -u origin feature/greeting

Step 7: Open a Pull Request

Via Web UI

1. Navigate to your repository on Kizuna
2. You'll see a banner: "feature/greeting has recent pushes — Compare & Pull Request"
3. Click it, or go to Pull Requests > New Pull Request
4. Fill in:
   • Title: "Add greeting application"
   • Description: Explain what you built and why
   • Reviewers: Add a teammate (or skip for now)
5. Click Create Pull Request

Via API

curl -X POST https://kizuna.yourcompany.com/api/v1/repos/my-team/hello-kizuna/pulls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add greeting application",
    "body": "First change — a simple greeting app",
    "head": "feature/greeting",
    "base": "main"
  }'

Step 8: Review and Merge

1. On the PR page, review the diff
2. If everything looks good, click Approve
3. Click Merge Pull Request
4. Choose merge strategy:
   • Merge commit — preserves full history
   • Squash — collapses into one commit
   • Rebase — linear history
5. Confirm the merge

Step 9: Git credentials

Not available yet: SSH keys.

Use HTTPS. Create a personal access token (Settings, Access tokens) with repo:write for push. The git password is that token. The username can be anything.

Step 10: Explore the Platform

Now that you've completed the basic workflow, explore these features:

Feature	Where to Find It
Issues	Repository > Issues tab
Kanban Board	Repository > Issues > Board view
CI/CD	Repository > Pipelines tab
Wiki	Repository > Wiki tab
Settings	Repository > Settings gear icon

What to Learn Next

• Tutorial: Team Setup — Configure your team's workflow
• Tutorial: Working with Agents — Set up your first AI agent
• Tutorial: CI/CD Setup — Automate your build pipeline
• Version Control Overview — Master Jujutsu workflows
• Code Review Guide — Effective PR reviews

Troubleshooting

Authentication Fails

• Verify your credentials at Settings > Account
• SSH is not available yet
• For HTTPS: use a personal access token as the git password, and check it has not expired

Push Rejected

• Check if branch protection rules are blocking direct pushes to main
• Create a feature branch and use pull requests instead

Jujutsu Not Recognized

• Install jj: cargo install jj-cli or download from GitHub releases
• Ensure jj is in your PATH