Search GitHub files from ClickUp, sync GitHub activity with ClickUp tasks, create GitHub pull requests, branches, and issues from ClickUp, and much more.

When setting up the integration, you'll link Spaces directly to GitHub repositories so you always know what work is related.

Workspace owners and admins can connect Spaces to their repos, allowing members to add their Github work to tasks.

Tasks in Spaces with a connected repo can be linked with commits, branches, and pull requests.

What you'll need

• The GitHub integration is available on every ClickUp plan.
• Only repository admins can add GitHub repositories to ClickUp. Once added, Workspace admins can add those repositories to ClickUp Spaces!
• Only Workspace owners and admins can update Workspace Settings in the App Center.
• Only Workspace owners and admins can add and link repositories to Spaces.
• Only Workspace owners and admins can create Workspace connections. Multiple Workspace connections are allowed.
• Members and above can create personal connections.
• Guests and limited members can't use the GitHub integration.

Connection types

The features and commands available depend on which type of connection you use.

Set up a personal connection

To set up a personal connection with GitHub:

1. In the upper-left corner, click your Workspace avatar and select Apps.

2. Browse for and select GitHub.

3. Click Connect.

4. Follow the prompts to authorize ClickUp, then click Done.

Set up a Workspace connection

There are three steps to set up a Workspace connection for GitHub in ClickUp:

1. Connect GitHub.

2. Attach GitHub repositories to your Workspace.

   Repos are needed so ClickUp can automatically link pull requests to their respective ClickUp tasks.

3. Link GitHub repos to ClickUp Spaces.

Step 1: Connect GitHub

To set up a Workspace connection for GitHub:

1. In the upper-left corner, click your Workspace avatar and select Apps.

2. Browse for and select GitHub.

3. At the top, click the Workspace tab.

   • Optional: Turn off Workspace Connected Search by clicking the toggle next to it.

4. Click Connect.

5. Follow the prompts to authorize ClickUp.

6. Choose which repositories you want to be searchable via Workspace Connected Search by clicking the Select repositories dropdown.

7. Once you've added repositories, click Save.
   

8. Click Next, then select Done.

Step 2: Add GitHub repositories to your Workspace

Only the connection owner can add repositories. 

Attaching a repo does not give ClickUp users access to your repo's codebase.

To add a repo to your Workspace:

1. From the GitHub page in the App Center, click Settings in the upper-right.
2. Click Add repo.
3. Select a repository. 
4. To add more repos, repeat steps 2 and 3.

If you don't see the correct repos, ensure you have signed in to the right account. A Workspace owner or admin must select each repository to connect. Linked repositories can be viewed in the App Center.

Step 3: Link GitHub repos to ClickUp Spaces

After adding repos to your Workspace, admins can connect each repo to one or more Spaces. Spaces can have multiple repositories added to them.

To link a repo to a Space:

1. From the GitHub page in the App Center, click Settings in the upper-right.
2. Click the name of the repo you want to link.
3. Click + Add Space.
   
4. Search for and select a Space.
5. To link additional Spaces, repeat steps 2-4.

Change the format of your branch name

If your organization uses a specific format for branch names, you can set it from the GitHub page in the App Center. When people create branches from ClickUp tasks, it will use this format.

The default format is: :taskId:_:taskName:_:username:

For example: CU-ae27de_Auto-generated-naming_John-smith

The available values are shown in the following table:

To change the format of your branch name:

1. From the GitHub page in the App Center, click Settings in the upper-right.
2. Under Auto-generated branch name, enter your preferred branch name format.
3. Click Save.

Search GitHub files using Connected Search

Use Workspace Connected Search to allow all Workspace members to search for any public files from the repositories you add.

Edit searchable repos

To edit which repos can be searched via Workspace Connected Search:

1. From the GitHub page in the App Center, click the Workspace tab.
2. Add or remove repositories from Workspace Connected Search:
   • Add new repositories: Click the selected repositories dropdown menu and select a repo.
   • Remove an existing repository: To the right of the repo, click the x icon.

Allow Super Agents to search GitHub

To allow a Super Agent to search files in your connected GitHub account, activate External Search for GitHub in its profile.

Link tasks from GitHub

ClickUp automatically associates new GitHub activity with tasks if you include a valid ClickUp task ID in any part of the pull request title, pull request description, branch name, or commit message.

When a ClickUp task ID is included in a pull request, a comment with a link to the ClickUp task will be posted in the pull request. A link will not display when manually pasting a pull request into a ClickUp task.

The comment will be posted using the GitHub account of the person who set up the repo and Space mapping.

The task ID must be formatted using one of these options:

#{task_id}

CU-{task_id}

{custom_task_id}

#{custom_task_id}

For example:

#1abc2de

CU-1abc2de

eng-123

#eng-123

Link tasks from ClickUp

Manually link ClickUp tasks to GitHub commits, branches, and pull requests from the task. Ensure the task is located in a Space that is linked to a repo.

To link a task:

1. Open a task and click the GitHub icon.
   
2. In the lower-right corner, click Add GitHub link.
3. Paste a link.
4. In the lower-right corner, click Add.

ClickUp task activity

GitHub activity can be accessed from the linked ClickUp task's Activity feed.

Task activity feeds sometimes collapse similar activity items to ensure you see the most important details.

You can take the following actions to locate GitHub activity in a task:

• Click Show more to reveal activity that has been hidden.
  
• When a branch is merged, commits display as a single activity item in the task's activity feed.
  • Click the link to all the commits to open a modal.
  • Click an individual commit to open it in GitHub.
• Filter task activity by Git items.
  

Missing activity 

If you can't locate certain activity, ensure that you're correctly referencing the ClickUp task ID to link activity in GitHub. You can use any of these three options to reference your ClickUp tasks on commits, branch names, and pull requests:

#{task_id}

CU-{task_id}

{custom_task_id}

For example:

#1abc2de

CU-1abc2de

prefix-1

You can also manually link ClickUp tasks with GitHub commits, branches, and pull requests from the ClickUp task.

GitHub link previews

When you paste a GitHub link into a ClickUp task, Chat, or Doc, you'll see the option to paste it as a preview, mention, or URL.

Create GitHub issues, branches, and pull requests from ClickUp

Create new issues, branches, and pull requests directly from tasks. 

Ensure the task is located in a Space that is linked to a repo and you have a personal connection set up.

To create an issue, branch, or pull request:

1. Open a task and click the GitHub icon.
   On the right, you'll see suggested branch names and commit messages you can copy to your clipboard. You can also copy the task ID from here.
2. In the lower-right corner, click Add GitHub link.
3. Choose one of the following options:
   • New GitHub Issue
   • New GitHub Branch
   • New GitHub Pull Request
4. Name the issue, branch, or pull request.
5. Select a repository and fill out the information. Add a source branch and target branch if applicable.
   
6. Click Create.

GitHub panel in tasks

Tasks in Spaces that are linked to repos have a GitHub icon that you can click to see every GitHub link posted in the task.

GitHub task activity uses the person's ClickUp username, or their GitHub username if they don't have a ClickUp account.

Update task statuses from GitHub

You can update the status of a ClickUp task when you link a commit, push a commit, or create a pull request. ClickUp automatically picks up new GitHub activity and associates it with tasks if you include a valid task ID in any part of the pull request title, pull request description, branch name, or commit message.

The task ID must be formatted using one of these options:

#{task_id}[status]

CU-{task_id}[status]

{custom_task_id}[status]

#{custom_task_id}[status]

To update a task status:

1. Add the ClickUp task ID in any part of the commit or pull request message.
2. Include the updated task status in square brackets.

For example: #ud5b[ready]

All formats listed in the Link tasks from GitHub section of this article can be used. To ensure proper formatting, do not add a space between the task ID and status information.

You can also update task statuses using GitHub Automations!

Manage GitHub issues, branches, pull requests, and commits from ClickUp

After you link issues, branches, pull requests, or commits, they are listed when you click the GitHub icon in a task. Use the ellipsis ... menu to copy the link or delete the item.

Once you link a GitHub item, the following information is displayed in your ClickUp task:

Issue information

After an issue is linked, you can see the following details:

• The person who opened the issue, known as the author
• Any assigned reviewers
• Link created
• Repository
• The issue status.
• URL

Branch information

After a branch is linked, you can see the following details:

• The person who created the branch, known as the author
• Link creator
• Repository
• URL

Pull request information

After a pull request is linked, you can see the following details:

• The person who opened the pull request, known as the author
• Any assigned reviewers
• Assignees
• Line changes
• Link created
• Repository
• Source branch
• Target branch
• The pull request status
• URL

Commit information

After a commit is linked, you can see the following details:

• The person who created the commit, known as the author
• Changed files
• Line changes
• Link created
• Repository
• URL

View pull requests in List or Table view

Add the Pull Requests column to any List view or Table view to quickly view your GitHub pull requests from a high level.

Connection issues

Sometimes, the wrong GitHub account is linked or there is an issue with the connection. In this scenario, you can try disconnecting and reconnecting your repositories or entire account.

These actions do not impact anyone's ability to access repos using their GitHub account through GitHub.

To disconnect a repository:

1. In the App Center, select GitHub.
2. In the upper-right corner, click Settings.
3. To the right of the repository, click the ellipsis ... icon.
4. Click Delete from ClickUp.

Disconnect GitHub from ClickUp

If you no longer need to access GitHub files in ClickUp, you can disconnect the integration:

1. In the App Center, select GitHub.

2. Select the Workspace tab.

   Only owners and admins can disconnect Workspace connections.

3. Next to Connected, click the ellipsis ... menu.
4. Select Disconnect.
5. To confirm, click Disconnect.

OAuth scopes

Below is a table of all OAuth scopes for the GitHub integration so you can make informed security and compliance decisions before enabling it in your Workspace.