Kizuna Help

Appearance

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 ​

Step 1: Create Your Account ​

On Kizuna Cloud ​

  1. Visit cloud.kizuna.codes and click Sign Up
  2. Authenticate with GitHub, GitLab, or email
  3. Choose a username — this is your identity across Kizuna

On Self-Hosted ​

  1. Navigate to your instance URL (e.g., https://kizuna.yourcompany.com)
  2. Click Register (or use SSO if your admin configured OIDC)
  3. Complete the registration form

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 ​

Ask your team admin to invite you, or use an invitation link if one was shared.

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 ​

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

With Git ​

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

With the CLI ​

bash
# 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:

bash
# 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 ​

bash
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 ​

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

With Git ​

bash
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 ​

bash
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: Set Up SSH Keys (Optional) ​

For passwordless Git/Jujutsu access:

  1. Generate a key if you don't have one:
    bash
    ssh-keygen -t ed25519 -C "your@email.com"
  2. Go to Settings > SSH Keys
  3. Click Add SSH Key
  4. Paste your public key (~/.ssh/id_ed25519.pub)
  5. Update your clone URL:
    bash
    # Jujutsu
jj git remote set-url origin git@kizuna.yourcompany.com:my-team/hello-kizuna.git

# Git
git remote set-url origin git@kizuna.yourcompany.com:my-team/hello-kizuna.git

Step 10: Explore the Platform ​

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

FeatureWhere to Find It
IssuesRepository > Issues tab
Kanban BoardRepository > Issues > Board view
CI/CDRepository > Pipelines tab
WikiRepository > Wiki tab
SettingsRepository > Settings gear icon

What to Learn Next ​

Troubleshooting ​

Authentication Fails ​

  • Verify your credentials at Settings > Account
  • For SSH: run ssh -T git@kizuna.yourcompany.com to test the connection
  • For HTTPS: ensure your token hasn't 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