ClickUp Integration

This article explains what the integration does, how to set it up, and what to expect once it is running.

---

1. What the integration does

1. One-click task import
   • As soon as you add the tag latchloop to a ClickUp task, LatchLoop automatically imports that task (and its subtasks) into your LatchLoop workspace.

2. Automatic analysis
   • When the task arrives in LatchLoop it is immediately analysed by the LatchLoop AI agent so that you can see estimates, code-plan drafts, and implementation notes without leaving your dashboard.

3. Optional “auto-build”
   • If the Auto-build toggle is ON (in Settings → General), LatchLoop will go further:
   – create a new branch in the linked GitHub repository,
   – generate the first commit(s),
   – open a Pull Request with the proposed changes,
   – and keep you updated inside ClickUp with a comment if it needs more information.
   • If Auto-build is OFF, the task is imported and analysed, but no code is written until you press Build from inside LatchLoop.

4. Status & feedback inside ClickUp
   • Whenever the agent replies (for example, if it needs clarification or when it has opened a PR) the message is posted back to the original ClickUp task so the whole team can follow along without switching tools.

---

2. One-time setup

2.1 Obtain a ClickUp API key

1. In ClickUp, click Avatar → Apps.
2. Generate a Personal Access Token.
3. Copy the key (keep it somewhere safe).

2.2 Enable the integration in LatchLoop

1. In LatchLoop, open Settings → Integrations → ClickUp.
2. Paste your API key.
3. Enter your Workspace (Team) ID – it is shown next to the workspace name in ClickUp’s URL or in the API docs.
4. Choose a Default Project (LatchLoop project) – imported tasks will be placed here automatically.
5. Click Save ClickUp Settings.

2.3 Create a webhook (so LatchLoop hears about tag changes)

There are two ways:

A. Recommended – use the Webhook Settings widget (no coding):

1. Stay on the same ClickUp Integration page and scroll to Agent Webhook.
2. Click Create Webhook.
3. Follow the prompts – LatchLoop will create the webhook in ClickUp on your behalf and store the secret securely.

B. Manual – from ClickUp Developer portal:

1. Go to ClickUp → Settings → Integrations → Webhooks → Add Webhook.
2. Events to select:
   • taskTagUpdated
   • taskCommentPosted (optional; currently unused)
3. URL: copy the Webhook URL shown in LatchLoop.
4. Secret: enter any long random string.
5. Save.
6. Back in LatchLoop, open Webhook Settings → Add Existing, paste the Webhook ID and Secret, and save.

That’s it! The connection is live.

---

3. Daily usage

1. Tag a task
   • In ClickUp open any task and add the tag latchloop.
   • Within a few seconds you’ll see a comment from LatchLoop Bot confirming that it is analysing the task.
2. Watch the task appear in LatchLoop
   • Go to your chosen LatchLoop project; the task will be listed with status “Imported”.
3. Review the AI plan
   • Open the task in LatchLoop to read the plan and (if Auto-build is ON) follow the pull-request link.
4. Iterate as needed
   • Update the description, attach files, or answer any bot questions directly in ClickUp – changes will sync automatically.

---

4. Frequently asked questions

Question	Answer
What if I remove the latchloop tag?	The task will remain in LatchLoop; removing the tag does not delete anything.
Can I trigger different commands via comments?	Not at the moment – the current release only reacts to the latchloop tag.
Who can add the tag?	Anyone in ClickUp with permission to edit tags can trigger the import.
How does LatchLoop choose a Git branch name?	The branch starts with the task short-ID plus a slug of the title, e.g. LL-123-add-login.
What if the agent needs more details?	The bot will leave a comment in ClickUp asking for clarification and will pause the build until you reply.
Is my ClickUp key safe?	Yes – your key is encrypted at rest and is only sent to ClickUp when making API calls on your behalf.

---

5. Troubleshooting

1. No task appears in LatchLoop
   • Make sure the webhook shows “Active” in ClickUp.
   • Verify that the latchloop tag was added (edits to an existing tag will not retrigger).

2. Bot says “Invalid ClickUp API key”
   • Regenerate the key in ClickUp → Apps and update it in LatchLoop settings.

3. Webhook error “Invalid signature”
   • The secret stored in ClickUp must match the one stored in LatchLoop Webhook Settings.

4. Pull request never created (with Auto-build ON)
   • Check that your GitHub repository is connected and the bot has permission to push branches.

If you are still stuck, send us the timestamp of the failing task and we will investigate the logs.

---

6. Security & permissions

• API keys and webhook secrets are encrypted and scoped to your user account – no other team can see them.
• LatchLoop only requests task:read and task:write scopes in ClickUp; it does not access docs, goals, or time tracking.
• All traffic between ClickUp, LatchLoop, and GitHub travels over HTTPS.

---

Happy building! 🚀
Have questions? Reach out at [email protected]