Integrate GitHub with ClickUp to link ClickUp tasks with activity in GitHub.

The Workspace owner or admins can connect Spaces to their repositories, allowing members to add their Github work to tasks.

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

What you'll need

• The GitHub integration is available on every ClickUp plan.
• Admin permissions are required for each repository to link them to ClickUp Spaces.
• Only Workspace owners and admins can update Workspace Settings in the App Center and link repositories to Spaces.
• Only Workspace owners and admins can create shared connections.
• Members and above can create private connections.
• Guests can't use 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 shared 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 PRs.

Private and shared connections

Learn about private and shared connections in our App Center article.

Set up the integration

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

1. Authorize 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: Authorize GitHub

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

To authorize GitHub:

1. Open the App Center:
   • ClickUp 2.0: In the lower-left corner, click your personal avatar and select App Center.
   • ClickUp 3.0: In the upper-left corner, click your Workspace name and select Apps. Click App Center.
2. Use the Development category or search All Apps for GitHub.
3. Select GitHub.
4. Click the Shared tab.
5. Click Connect.
6. Sign in to GitHub and authorize ClickUp.

Step 2: Attach GitHub repositories to your Workspace

Workspace owners and admins can choose which GitHub repositories to link to your ClickUp Workspace.

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.
   
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.

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.

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. Open a task and click the GitHub icon.
   

   Ensure the task is located in a Space that is linked to a repo.

2. Select the Pull Requests, Branches, or Commits tab.
   
3. Select a repo from the dropdown menu.
4. Choose a pull request or branch from the second dropdown menu.
   
5. Link your pull request, branch, or commit to the ClickUp task.
6. In GitHub, ClickBot will post a comment confirming the task has been linked.

See 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 username, or their GitHub username 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 a commit, push a commit, or create a pull request.

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]

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. Open a task and click 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. Open a task and click the GitHub icon.
2. In the lower-left, click New Pull Request.
3. Select a target and source branch.
4. Enter a description.
5. Click New 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.

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:

1. Open the App Center:
   • ClickUp 2.0: In the lower-left corner, click your personal avatar and select App Center.
   • ClickUp 3.0: In the upper-left corner, click your Workspace name and select Apps. Click App Center.
2. Use the Development category or search All Apps for GitHub.
3. Select GitHub.
4. Click the Private tab.
5. Next to Create a private connection, click Connect.
6. Sign in to GitHub and authorize ClickUp.

Remove your GitHub account from ClickUp

To remove your GitHub account:

1. Open the App Center:
   • ClickUp 2.0: In the lower-left corner, click your personal avatar and select App Center.
   • ClickUp 3.0: In the upper-left corner, click your Workspace name and select Apps. Click App Center.
2. Use the Development category or search All Apps for GitHub.
3. Select GitHub.
4. Click the Private tab.
5. Next to Connected, click the ellipsis ... icon.
6. Click Disconnect.

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

Remove the GitHub integration from a Workspace

Only Workspace owners and admins can remove the GitHub integration from a Workspace.

To remove the GitHub integration from GitHub in the App Center:

1. Click the Shared tab.
2. Next to Connected, click the ellipsis ... icon.
3. Click Disconnect.

Updated November 02, 2023 13:51