Intergrate GitHub

Setting Up GitHub Integration

The GitHub integration allows you to automatically sync GitHub issues with Todo2d tasks. When you create, update, or close issues in GitHub, the corresponding tasks in Todo2d will be updated automatically.

What Gets Synced

• Issue titles ↔ Task names
• Issue status (open/closed) ↔ Task completion status

Note: Comments, labels, assignees, milestones, and projects are not synced in the current version.

Step 1: Install the GitHub App

1. Navigate to the GitHub App installation page for Todo2d
2. Click “Install” and select the GitHub account or organization where you want to install the app
3. Choose which repositories you want to give Todo2d access to:
   • All repositories (recommended for full integration)
   • Selected repositories (choose specific repos)
4. Click “Install”

After installation, you’ll be automatically redirected back to Todo2d.

Step 2: Link Repositories to Workspaces

Once the GitHub App is installed, you need to connect specific repositories to your Todo2d workspaces:

1. In Todo2d, go to Account Settings → GitHub Integration
2. You’ll see the connections between GitHub repositories and Todo2d workspaces listed followed by a list of all known installations.
3. For each repository you want to sync:
   • Select the installation
   • Select the repository
   • Select the Todo2d workspace you want to link it to
   • Click “Create”

Pro tip: You can connect the same repository to multiple workspaces if needed and you can connect multiple repostories to the same workspace.

Step 3: Start Using the Integration

That’s it! Your GitHub integration is now active. Here’s what happens automatically:

When you create a GitHub issue:

• A new task appears in all connected Todo2d workspaces
• The task name matches the issue title
• Task attributes include the GitHub issue number and URL

When you update a GitHub issue:

• The corresponding Todo2d task(s) are updated automatically
• Title changes sync in both directions

When you close/reopen a GitHub issue:

• The task completion status updates automatically

When you update a Todo2d task:

• The GitHub issue title updates if you change the task name
• The GitHub issue is closed/reopend if you mark the task as complete
• Note: Creating or deleting tasks in Todo2d does NOT create or delete GitHub issues.
• Note: If a Todo2d-task was deleted and then the GitHub-issue is updated, the Todo2d-task will be recreated.

Managing Your Integration

View Connected Repositories

In Todo2d, go to Account Settings → GitHub Integration to see:

• All your GitHub installations
• Connected repositories and their linked workspaces

Disconnect a Repository

To stop syncing a repository:

1. Go to Account Settings → GitHub Integration
2. Find the repository connection you want to remove
3. Click “Delete”

Troubleshooting

My workspace are not listed

• Only paid workspaces are listed.

Tasks not syncing?

• By default, tasks are not placed on a map to prevent overcrowding. You can use the search function to add them to a map if needed. Check if this is the case by using the search function and search for the title of the github issue.
• Existing issues before integration setup won’t sync automatically, you need to modify them.

Integration not working?

• Verify the GitHub App is installed on the correct account/organization
• Check that the repository is connected to the right workspace
• Ensure you have the necessary permissions in both GitHub and Todo2d

Missing repositories?

• The GitHub App might not have access to those repositories
• Check your GitHub App installation settings

Security & Permissions

• Todo2d only accesses repositories you explicitly grant access to
• GitHub tokens are automatically managed and expire within 1 hour
• You can revoke access anytime through your GitHub App installations page