> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to ClickUp

> Connect Overcut to your ClickUp workspace to manage tasks, automate status updates, and trigger workflows from ClickUp events.

## What You Can Do

With ClickUp connected, Overcut agents can:

* **Create and Update Tasks**: Open new tasks or modify titles, descriptions, assignees, tags, and statuses
* **Comment on Tasks**: Post comments to keep task threads in sync with automated workflows
* **Trigger Workflows**: Automatically start workflows when tasks are created, updated, status-changed, or commented on
* **Search Tasks**: Find and reference existing tasks across your ClickUp Spaces

## Prerequisites

* A **ClickUp workspace** with access to the Spaces you want to connect
* An active **Overcut workspace**
* A **dedicated ClickUp service account** with **Admin** (or Owner) role for initial setup. Can be downgraded to **Member** after OAuth authorization

## Setup Overview

ClickUp integration uses OAuth authorization tied to a specific user account. Because all Overcut operations will appear under the authorizing user's name, we strongly recommend using a **dedicated service account** rather than a personal account.

**Service Account Advantages:**

* **Consistent Bot Identity**: All automated actions appear under a single, recognizable bot user
* **Loop Prevention**: Overcut can reliably filter out its own activity to avoid infinite trigger loops
* **Independence**: The integration survives team member departures and role changes
* **Clear Attribution**: Team members can distinguish automated changes from manual work

<Note>
  ClickUp charges per workspace member. Factor in the additional seat cost when creating a dedicated service account.
</Note>

## Setup Steps

<Steps>
  <Step title="Create a ClickUp Service Account">
    Create a dedicated account to act as the Overcut bot identity.

    1. **Create a new ClickUp user** in your workspace:
       * Name: `Overcut Bot` (or similar)
       * Email: Use a shared/team-managed email (e.g., `overcut-bot@yourcompany.com`)
    2. **Grant access** to the Spaces where you want Overcut to operate
    3. Assign the account an **Admin** role in the workspace. This is required for the initial OAuth authorization

    <Note>
      Using a dedicated service account ensures Overcut's access remains stable even if team members leave, and provides a clear, consistent identity for all bot operations.
    </Note>
  </Step>

  <Step title="Authorize Overcut via OAuth">
    Connect the service account to Overcut using OAuth.

    1. **Sign in to ClickUp** as the service account
    2. In the same browser, open your Overcut workspace and go to **Settings → Integrations**
    3. Click **Connect ClickUp**
    4. You will be redirected to ClickUp's authorization screen
    5. **Approve the Overcut application** to grant the required permissions
    6. Complete the OAuth flow to link the service account to Overcut
  </Step>

  <Step title="Downgrade to Member (optional)">
    After OAuth authorization is complete, you can reduce the service account's role to **Member**. Member access is sufficient for all ongoing Overcut operations: creating tasks, posting comments, managing webhooks, and receiving events. The account only needs access to the relevant Spaces.

    <Note>
      ClickUp validates that the webhook creator still has access to the target Space before each webhook fires. As long as the service account remains a Member with access to the connected Spaces, webhooks will continue to work.
    </Note>
  </Step>

  <Step title="Select Spaces and Verify">
    Choose which ClickUp Spaces should appear in Overcut and confirm the connection.

    1. After authorization, select the **ClickUp Spaces** you want to use as ticket repositories in Overcut
    2. Click **Save & Finish**
    3. Verify that your selected Spaces appear under **Repositories → Tickets**
    4. Test the connection by creating a simple workflow with a ClickUp trigger
  </Step>
</Steps>

## Using ClickUp in Your Workflows

Once connected, ClickUp Spaces appear as available ticket repositories when you:

* Add a **Source** to a workflow
* Configure a **Trigger** that monitors ClickUp events (task creation, updates, status changes, comments)
* Set up **Actions** that create, update, or comment on tasks

### Common Operations

<CardGroup cols={2}>
  <Card title="Create a Task" icon="circle-plus">
    Generate a new ClickUp task from any trigger: failing CI run, Slack command, or scheduled check.
  </Card>

  <Card title="Update a Task" icon="pen-to-square">
    Edit titles, descriptions, tags, assignees, or statuses as your workflow progresses.
  </Card>

  <Card title="Comment on a Task" icon="comment">
    Post automated comments to keep task threads in sync with workflow progress.
  </Card>

  <Card title="Close a Task" icon="check-double">
    Mark tasks as complete or closed when a pipeline finishes or a condition is met.
  </Card>
</CardGroup>

### Example Workflow

```yaml theme={"dark"}
steps:
  - id: "clone-repo"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.[identify-repos].[0].repoFullName}}"
      branch: "main"

  - id: "analyze-task"
    action: "agent.run"
    params:
      instruction: |
        Analyze ClickUp task #{{trigger.issue.number}}: "{{trigger.issue.title}}"

        Description:
        {{trigger.issue.body}}

        Provide a fix and update the task with your findings.
```

## Provider-Specific Behaviors

* **Space as Repository**: Each ClickUp Space you select is treated as a separate ticket repository in Overcut. You can target specific Spaces in triggers and actions.
* **Tags as Labels**: ClickUp tags are mapped to the normalized `labels` field. Use tag names in trigger filters and workflow conditions.
* **Custom Statuses**: ClickUp supports custom statuses per Space. Trigger filters for **Status From** and **Status To** use the exact status names configured in your Space (for example, "To Do", "In Progress", or "Complete").
* **Status Transitions**: ClickUp provides both the previous and new status for status change events, so both `trigger.statusFrom` and `trigger.statusTo` are available.
* **Task relationships**: Agents can create, remove, and read linked task relationships in ClickUp. ClickUp supports a single link type, `related` (pass that value or omit the type). Linking is scoped to the connected workspace and Space. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers.
* **Task Title in Webhooks**: ClickUp webhook payloads for non-creation events may not include the task title. For these events, `trigger.issue.title` may be empty.

## Permissions

The ClickUp OAuth integration grants full API access to the authorized workspace. Overcut uses these permissions to:

* Read and write tasks across selected Spaces
* Create and manage comments
* Create webhooks for event notifications
* Access Space and workspace information

<Tip>
  Scope your service account's access to only the relevant Spaces to follow the principle of least privilege.
</Tip>

## Next Steps

* Learn about [workflow quick starts](/docs/quick-starts/index) for automation recipes
* Set up [repository mapping](/docs/repositories/repository-mapping) to link ClickUp Spaces to code repositories
* Explore [triggers](/docs/workflows/triggers) to automate workflows from ClickUp events