Link Spaces directly with 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 can't use the GitHub integration.

• Workspace Connected Search is available on the Business Plan and above.

• Personal Connected Search is not available for the GitHub integration.

Real-world example

The engineering team for your mobile app and the website development team work in different repos and separate Spaces, within the same GitHub organization and ClickUp Workspace.

To get started with the integration:

1. The Workspace owner or admin creates a Workspace GitHub connection.
2. The mobile app manager connects the app-mobile GitHub repo to the mobile app development Space.
3. The website manager connects the website GitHub repo to the marketing website Space.
4. Tasks in the mobile app development and marketing website Spaces now display the GitHub icon, allowing both teams to link their tasks with GitHub commits, branches, and pull requests.

Set up the integration

There are four steps to set up the GitHub integration in ClickUp:

1. Connect GitHub.
2. Attach GitHub repositories to your Workspace.
3. Link GitHub repos to ClickUp Spaces.
4. Optionally, you can set a custom branch name format.

Step 1: Connect GitHub

You'll need to be a Workspace owner or admin to set up a Workspace Connection for GitHub.

You can set up a GitHub connection from the App Center or Command Center.

From the App Center:

1. Search for and select GitHub.
2. Click the Workspace tab.
   

   You can also set up a personal connection to create pull requests and branches from ClickUp. Personal connections can also be used to link existing pull requests, branches, and commits directly from ClickUp tasks. 

3. Click Connect.
4. Sign in to your GitHub account to authorize access.

From the Command Center:

1. Under the search bar, click Apps.
2. Under GitHub, click Connect.
3. Under Workspace Connections, click Connect.
4. Sign in to your GitHub account to authorize access.

Step 2: Attach GitHub repositories to your Workspace

Workspace owners and admins can choose which GitHub repositories to link to their ClickUp Workspace. The owner or admin must also be a GitHub repository admin.

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

To add a repo to a Workspace:

1. Open GitHub in the App Center.
2. Click Workspace Settings.
3. Next to Connect Repositories to ClickUp, click Add repo.
4. Select all repositories you want to add.

If you don't see the correct repos, you may have signed in with the wrong GitHub account.

Step 3: Link GitHub repos to ClickUp Spaces

After adding repos to your Workspace, you can add each repo to one or more Spaces. Each ClickUp Space can have multiple repositories added.

You can add or remove repos from Spaces at any time.

To link a repo to a Space:

1. Open GitHub in the App Center.
2. Click Workspace Settings.
3. Click the name of the repo you want to link.
4. Click + Add Space.
5. Repeat for additional Spaces you want to link.

Step 4: Set your branch name format

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 options are shown in the following table:

To set your default name format from GitHub in the App Center:

1. Click Workspace Settings.
2. Under Auto-generated branch name, enter your preferred branch name format.
3. Click Save.

Search GitHub files using Connected Search

When using a Workspace connection on the Business Plan and above, you can use Workspace Connected Search to enable all Workspace members to search for any public files from the repositories you add. Private files can not be searched.

From the App Center:

1. Search for and select GitHub.
2. Click the Workspace tab.
3. Click the toggle next to Workspace Connected Search.
4. Next to your Workspace connection, click Save.
5. GitHub files in the repositories you've added will display when searching your Workspace.

Pin GitHub to Command Center

Filter search results to GitHub files by pinning GitHub to Command Center.

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

You can also manually link ClickUp tasks with GitHub commits, branches, and pull requests from the ClickUp 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.
   

   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. Paste a link.
4. In the lower-right corner, click Add.

Create GitHub issues, branches, and pull requests from ClickUp

You can also create new issues, branches, and pull requests directly from tasks. Ensure the task is located in a Space that is linked to a repo.

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.

See GitHub activity in ClickUp

To see all GitHub activity for a task, click the GitHub icon on the right side of 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 display on the right side of your task when you click the GitHub icon. 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

Add your GitHub account to ClickUp

Workspace members can link their GitHub accounts to their ClickUp account in advance or when they create a branch or pull request.

To add your GitHub account from the App Center:

1. Search for and select GitHub.
2. Click the Personal tab.
3. Next to Create a personal connection, click Connect.
4. Sign in to GitHub and authorize ClickUp.

Disconnect the GitHub integration

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

1. Search for and select GitHub.
2. Select the Workspacce 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.