Does your organization use ClickUp for work management, but your software team uses GitHub to develop code? Use the GitHub integration to link ClickUp tasks and GitHub activity.

You can enable this integration for your Workspace and connect specific Spaces with one or more repositories (repos) in GitHub.

More than one person can authorize their Github account with a Workspace, so different software teams can manage their work in the same ClickUp Workspace. They can keep things separate by connecting their respective repos with separate Spaces.

Spaces with connected repos will show the GitHub icon and activity on ClickUp tasks.

You can associate GitHub commits, branches, and pull requests with ClickUp tasks. Create GitHub Automations to keep your work in ClickUp up to date.

What you'll need

• The GitHub integration is available on all ClickUp Plans.
• You'll need to be a Workspace owner or admin to set up integrations and link GitHub with Spaces.
• You'll need admin permissions to each repository to link them to a ClickUp Space.
• Workspace members can link their GitHub and ClickUp accounts to create new branches and pull requests from ClickUp.
• Guests cannot use the GitHub integration.

Task view 3.0 is currently in beta. Join the 3.0 waitlist. The following instructions apply to both Task view 2.0 and Task view 3.0.

Set up the integration

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

1. Authorize GitHub for your ClickUp Workspace.
2. Attach GitHub repositories to your Workspace.
3. Link GitHub repos to ClickUp Spaces.
4. Set your branch name format.

For example, the marketing team uses GitHub to manage the codebase of the organization's website. A ClickUp admin with admin permissions to the website repo authorizes GitHub. They add the website repo to the organization's Workspace and add that repo to the Marketing Space.

For the same organization, the software team uses GitHub to manage the codebase of a mobile app.

Another ClickUp admin with admin permissions to the app-mobile repo authorizes GitHub for the same Workspace. They add the app-mobile repo to the Workspace and add that repo to the Engineering Space.

The marketing and engineering teams are able to connect their tasks and GitHub activity for their respective repos.

Authorize GitHub for your ClickUp Workspace

You'll need to be a Workspace owner or admin to authorize GitHub for your ClickUp Workspace.

To authorize GitHub:

1. From your Workspace avatar menu, click Integrations.

2. Click the GitHub logo to get started.

3. Click Activate GitHub for Team.

4. Click + Add GitHub.

5. If you are logged out of GitHub, you'll be prompted to sign into GitHub.

6. Review the required permissions.

7. To add organization repositories, click Grant to allow ClickUp to organization access.
   

8. Click Authorize ClickUp.

Attach GitHub repositories to your Workspace

You can choose which GitHub repositories to link to your ClickUp Workspace. For example, you can link your personal repos with your personal Workspace, and your organization repos with your software team's Workspace.

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

To add a repo to a Workspace:

1. From the integrations page, click the GitHub icon.
2. Under My repositories from GitHub, you'll see a list of repositories
3. Click + Add to ClickUp to add a repo to your Workspace.
4. Repeat for any other repos you want to add.

Not seeing the right repos? You may have signed in with the wrong GitHub account. Make sure you're signed into GitHub with the account you want to use, and click Re-authenticate Github. Learn more about these options in our troubleshooting GitHub help article.

Link GitHub repos to ClickUp Spaces

Now that you've authorized GitHub and added repositories to your Workspace, you can add each repo to one or more Spaces. You can add or remove repos from Spaces at any time.

1. From the integrations page, click the GitHub icon.
2. Under the GitHub repositories added to ClickUp section, click the dropdown menu next to a repo.
3. Select one or more Spaces.
4. You can now link GitHub activity from that repo on tasks in the selected Space(s).
5. Repeat for any other repos you want to add to Spaces.

Set your branch name format

If your organization uses a specific format for branch names, you can set it on the Integrations page. 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:

Value	Description
:username:	The user name of the ClickUp user account that created the branch. Spaces are replaced with a dash.
:taskId:	The ID of the ClickUp task where the branch is created. Includes the required prefix.
:taskName:	The name of the task where the branch is created. Spaces are replaced with a dash.

 

To set your default branch name format:

1. From the integrations page, click the GitHub icon.
2. Enter your preferred branch name format.
3. Click Save.

Link tasks from GitHub

ClickUp will automatically pick up new GitHub activity and associate it with tasks if you include a valid ClickUp task ID in any part of the pull request title, branch name, or commit message.

When linking tasks to a new pull request in GitHub, you'll see a comment confirming the task has been linked.

For personal repos, the comment will be posted using the repo owner's GitHub account. For organization repos, the comment will be posted using the GitHub account of the repo owner who added the repo to the ClickUp Workspace.

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

#{task_id}

CU-{task_id}

{custom_task_id}

For example:

#1abc2de

CU-1abc2de

eng-123

Link tasks from ClickUp

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

1. Click the GitHub icon on any task.

2. Select the pull request, branch, or commit tab.

3. Select a repo, then choose a branch.

4. Link your pull request, branch, or commit to the ClickUp task.

5. In GitHub, ClickBot will post a comment confirming the task has been linked.

View GitHub activity in ClickUp

You can see all GitHub activity in a linked task's activity feed, along with task comments and other task updates.

When a branch is merged, commits display as a single activity item in the task or the task's activity feed. A link to all the commits opens a modal where you can click an individual commit to open it in GitHub.

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

Update the task status from GitHub

You can update the status of a ClickUp task when you link or push a commit or when you create a pull request.

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]

Watch the task's status change in this GIF.

Manage GitHub from ClickUp

You can manage GitHub from ClickUp tasks, including:

• Copy the ClickUp task ID with a valid prefix, for example: #1abc2de
• Copy a suggested branch name.
• Create and checkout a new branch.
• Copy a commit message to link tasks.
• Create a new branch.
• Create a pull request.

To manage GitHub from a task:

1. Click on the GitHub icon.
2. Use the options displayed on the left:
   • Click the copy button next to each option to copy the text to your clipboard.
   • Click Create branch or New Pull request.

Create and manage pull requests from ClickUp

To create a new pull request in ClickUp from tasks:

1. Click on the GitHub icon.

2. Click the New Pull Request button.

3. Select a target and source branch.

4. Enter a description.

5. Create the pull request.

6. In GitHub, ClickBot will post a comment to the pull request confirming the task has been linked.

Once a pull request is linked, you can see the following details from the ClickUp task:

• The person opened the pull request.
• Any assigned reviewers.
• CI/CD status.
• The pull request status including open, review requested, under review, merged, and closed.

Adding a GitHub account to ClickUp

Once a Workspace owner or admin has set up the integration, Workspace members can link their GitHub accounts to create branches and pull requests on tasks.

Workspace members (not guests) can add their GitHub account to their ClickUp account in advance or when they create a branch or pull request.

To connect or disconnect a GitHub account to a ClickUp account:

1. Click on your user avatar in the lower-right corner of your Workspace.

2. Select My settings.

3. Click GitHub under My Apps in the sidebar.

4. To connect your GitHub account, click Connect and log in to GitHub.

5. To disconnect your GitHub account, click Disconnect.

   Disconnecting your Github account does not impact the integration between GitHub and the ClickUp Workspace.

Remove the GitHub integration

Only Workspace owners and admins can remove the GitHub integration.

To remove the GitHub integration:

1. In the lower-left corner, click your avatar.
2. Select Integrations.
3. Select GitHub.
4. In the lower-right corner, click Remove GitHub.

Updated March 15, 2023 05:23