Klara for Developers

Overview

The GitHub Projects integration allows Pro tier users to view and manage their GitHub Project items directly in Klara's Eisenhower Matrix. Your GitHub issues appear as tasks, complete with deadline, importance, and effort mappings from your project fields. When you complete a task in Klara, the status updates in GitHub automatically.

Requirements:

• Pro tier subscription
• GitHub account with access to GitHub Projects V2

What you can do:

• Connect personal and organization GitHub Projects
• Map project fields to Klara's deadline, importance, and effort
• View GitHub issues in your Eisenhower Matrix
• Complete tasks and have status write back to GitHub
• Add completion notes as comments on GitHub issues

Connecting GitHub

Step 1: Start the Connection

1. Go to Settings (click your avatar in the top right)
2. Scroll to the GitHub Integration section
3. Click Connect GitHub

Step 2: Authorize Klara

You will be redirected to GitHub to authorize Klara. The app requests the following permissions:

• Read access to projects - Required to fetch your project items
• Read access to your profile - Required to identify your GitHub account

Click Authorize to grant these permissions and return to Klara.

Step 3: Install the GitHub App

You must install the Klara GitHub App to use the integration:

1. Visit the Klara GitHub App installation page
2. Click Install
3. Select your personal account or organization
4. Choose which repositories to grant access to (or select all)
5. Click Install to confirm

The GitHub App is required for all GitHub integration features:

• Accessing project items and fields
• Reading issue content from your repositories
• Writing status updates when completing tasks
• Posting completion comments on issues

Note: You must install the GitHub App on each account (personal or organization) that owns projects you want to connect.

Selecting a Project

After connecting GitHub and installing the app, you can select which project to sync:

1. In the GitHub Integration section, click Select Project
2. Browse your projects grouped by owner (personal and organizations)
3. Click on a project to select it
4. Configure field mappings (see next section)
5. Click Connect to start syncing

Note: You can only connect one GitHub Project per Klara project. To manage multiple GitHub Projects, create separate Klara projects for each.

Configuring Field Mappings

Field mappings tell Klara how to read your GitHub Project fields. This determines how tasks appear in the Eisenhower Matrix.

Deadline Field

Map a Date type field from your project to set task deadlines.

Example: If your project has a "Due Date" field, select it as the deadline mapping. Tasks with a due date will show that deadline in Klara.

Importance Field

Map a field to determine task importance (1-5 scale).

Option 1: Number field If you use a numeric importance field (1-5), select it directly.

Option 2: Single-select field If you use labels like "P0", "P1", "P2", etc., map each value to an importance level:

Effort Field

Map a field to determine task effort (1-5 scale). This affects urgency calculation.

Option 1: Number field If you use a numeric effort/size field (1-5), select it directly.

Option 2: Single-select field If you use T-shirt sizes or story points, map each value:

Status Field

Map a Single-select field that represents your workflow status. This is required for write-back functionality.

Configure completion statuses: Select which status values represent a completed task. When a task has one of these statuses, it appears as completed in Klara.

Example completion statuses:

• Done
• Closed
• Shipped
• In Review (if you consider review complete)

How GitHub Items Appear in Klara

Once configured, your GitHub issues appear as tasks in Klara with a GitHub icon indicator.

What syncs from GitHub

What does NOT sync

• Pull Requests (only Issues)
• Draft issues
• Closed issues
• Issue comments (except completion notes you add)

Automatic Quadrant Placement

GitHub tasks are placed in quadrants based on your field mappings:

1. Deadline determines urgency (closer deadlines = more urgent)
2. Importance determines the importance dimension
3. Effort affects urgency calculation (higher effort = needs to start sooner)

Tasks without a deadline or importance may appear in the "Maybe" or "Skip" quadrants.

Completing Tasks

When you complete a GitHub task in Klara, the status updates in GitHub.

How to Complete

1. Click on a GitHub task to expand it
2. Click the Complete button
3. Select the target status from the dropdown (e.g., "Done")
4. Optionally add a completion note
5. Click Mark Complete

What Happens

1. The issue's status field updates in GitHub
2. If you added a note, it posts as a comment on the issue
3. The task moves to completed state in Klara
4. Other team members see the update in GitHub

Requirements for Write-back

For status updates to work:

• GitHub App must be installed on the account that owns the project
• Your account must have write access to the project
• Status field must be configured in field mappings

Sync and Refresh

Automatic Sync

GitHub items sync automatically:

• When you open Klara
• When changes occur via webhooks
• Every 15 minutes in the background

Manual Refresh

Click the refresh button next to the GitHub project badge to force a sync. This is useful if:

• You just made changes in GitHub
• The automatic sync seems delayed
• You want to verify the latest state

Sync Indicator

The sync indicator shows:

• Last synced time - When data was last fetched
• Sync in progress - When actively fetching
• Error state - If sync failed (with retry option)

Disconnecting GitHub

To disconnect your GitHub account:

1. Go to Settings
2. In the GitHub Integration section, click Disconnect
3. Confirm the disconnection

This removes:

• Your GitHub connection
• All project connections
• Cached GitHub items

Your tasks in GitHub remain unchanged.

Troubleshooting

"Unable to access some items"

This message appears when Klara cannot access certain issues. Common causes:

Missing repository access: The GitHub App may not be installed on all repositories in your project. Install the app on the missing repositories or grant access to "All repositories".

Private repository: Ensure the GitHub App has access to the repository containing the issues.

"GitHub App may not have write access"

When completing tasks fails:

1. Verify the GitHub App is installed on the account owning the project
2. Check the app has "Issues: Read & Write" permission
3. Ensure your account has write access to the project

"Rate limit exceeded"

GitHub limits API requests. If you hit the limit:

1. Wait for the reset time shown in the error
2. Reduce manual refresh frequency
3. The limit resets hourly

Tasks not appearing

If expected issues are missing:

1. Verify they are open (not closed)
2. Verify they are not drafts
3. Verify they are Issues (not PRs)
4. Check they belong to the connected project
5. Try a manual refresh

Wrong quadrant placement

If tasks appear in unexpected quadrants:

1. Check field mappings are correct
2. Verify the issue has values for mapped fields
3. Tasks without deadline/importance default to lower priority

Status not updating in GitHub

If completing tasks doesn't update GitHub:

1. Verify GitHub App is installed with write permissions
2. Check you have write access to the project
3. Verify status field is configured in mappings
4. Check for error messages in the completion dialog

Best Practices

Field Mapping Strategy

Keep it simple:

• Start with just deadline and status mappings
• Add importance/effort mappings once you establish a workflow

Use consistent values:

• Define clear meanings for importance levels
• Document your mapping in your team wiki

Project Organization

One GitHub Project per Klara project: Since each Klara project connects to one GitHub Project, organize accordingly:

• Work project → Work GitHub Project
• Personal project → Personal GitHub Project

Filter by status: Use status filtering to focus on active work and hide completed items.

Team Workflows

Shared understanding: Ensure team members understand:

• What importance levels mean
• Which statuses count as "complete"
• When to complete in Klara vs. GitHub

Completion notes: Use completion notes to document:

• How the issue was resolved
• Any follow-up needed
• References to related PRs

Security and Privacy

Token Storage

Your GitHub OAuth token is:

• Encrypted using AES-256-GCM before storage
• Stored in Klara's secure database
• Never exposed to the browser after initial connection
• Deleted when you disconnect

Data Access

Klara only accesses:

• Project fields and items you explicitly connect
• Issue metadata (not full repository contents)
• Your GitHub profile (username, avatar)

Revoking Access

To fully revoke Klara's access:

1. Disconnect in Klara Settings
2. Go to GitHub → Settings → Applications
3. Find Klara and click Revoke
4. Uninstall the GitHub App from your account/organization settings

Frequently Asked Questions

Can I connect multiple GitHub Projects?

Each Klara project can connect to one GitHub Project. Create multiple Klara projects to manage multiple GitHub Projects.

Is GitHub integration shared with collaborators?

No. GitHub integration is personal to each user. Each person must connect their own GitHub account to see their own GitHub Projects in Klara. Collaborators on a shared Klara project cannot see each other's connected GitHub data.

Will changes I make in GitHub appear in Klara?

Yes. Changes sync automatically via webhooks or on the next manual/automatic refresh.

Can I create GitHub issues from Klara?

Not currently. You create issues in GitHub, and they appear in Klara after sync.

Does this work with GitHub Enterprise?

Not currently. Only GitHub.com is supported.

What happens to GitHub tasks if I cancel my subscription?

You lose access to the GitHub integration. Tasks remain in GitHub unchanged. If you resubscribe, reconnect your project to restore the integration.