@zentus/gitclick
v0.0.14
Published
lib and cli for github<->clickup integration
Downloads
14
Maintainers
Readme
@zentus/gitclick
A CLI tool for Clickup Task to GitHub Pull Request syncing and cross-referencing.
Installation
npm install -g @zentus/gitclick
Setup
Add the following environment variables to ./.env
:
GITCLICK_CLICKUP_PERSONAL_TOKEN="your_clickup_token"
GITCLICK_GITHUB_PERSONAL_TOKEN="your_github_token"
GITCLICK_GITHUB_BASE_BRANCH="your_base_branch" # (optional) default: "main"
Or export them from your shell rc file, (~/.bashrc
or ~/.zshrc
etc):
export GITCLICK_CLICKUP_PERSONAL_TOKEN="your_clickup_token"
export GITCLICK_GITHUB_PERSONAL_TOKEN="your_github_token"
export GITCLICK_GITHUB_BASE_BRANCH="your_base_branch" # (optional) default: "main"
If you added them to a shell rc file, restart your terminal to start using the program.
Usage
Sync current Branch (using glick
alias):
glick
Sync current Branch and undraft Pull Request:
gitclick sync --undraft
Sync new Branch:
gitclick sync SOME-1337
Task Tags will be used to try to set a branchType
prefix.
If the Task with Task Custom ID SOME-1337
has the Task Tag bug
, the Branch Name will be bugfix/some-1337
.
If the Task with Task Custom ID SOME-1337
has the Task Tag Feature
, the Branch Name will be feature/some-1337
.
If no matching Task Tags are found, the Branch Name will be some-1337
.
Sync new Branch as non-draft
gitclick sync SOME-1337 --undraft
Commands
gitclick sync
A Pull Request will be created, if it doesn't already exist
The Pull Request Title will be set to the current Task Name
The Pull Request Body will be set to include a link to the Task
The Pull Request Body will be set to include the current Markdown Description of the Task
A Task Comment will be created in the Task, containing the Pull Request URL, if such a Task Comment doesn't already exist in the Task
Arguments
1. Create new Branch (Optional)
Format: {branchType}{separator}{taskId}{freetext}
If not provided, the current Branch will be used. The current Branch must include a Task Custom ID of an existing Task.
If provided, a new Branch will be created with GITCLICK_GITHUB_BASE_BRANCH
as its Base Branch. At least subargument taskId
must be included.
Subarguments
branchType
(Optional)
A string to use as prefix of the new Branch Name. Commonly feature
, bugfix
, refactor
or docs
etc (See GitClick.branchTypes). If not provided, current Task Tags will be used to try to set a branchType
.
separator
(Optional)
A character separating branchType
and taskId
. Commonly /
or -
. Must be /
if using an uncommon branchType
string.
taskId
(Required)
The Task Custom ID of an existing Task.
freetext
(Optional)
A Branch Name suffix. May include spaces, as it will be normalized.
Flags
undraft
(Optional)
If provided, the Pull Request will be set to Ready for review
.
Note: If you want to set a Ready for review
Pull Request back to Draft
, you currently need to do it manually in GitHub due to GitHub API limitations.
base
(Optional)
If provided, will override GITCLICK_GITHUB_BASE_BRANCH
.
Examples
With suffixed Branch Name:
gitclick sync SOME-1337-important-changes
Branch Name will be some-1337-important-changes
.
With suffixed Branch Name as free text:
gitclick sync SOME-1337 lots of stuff
Branch Name will be some-1337-lots-of-stuff
.
With specified common branchType
:
gitclick sync bug/SOME-1337 important changes
Overrides any branchType
that could be determined from Task Tags
Branch Name will be will be bugfix/some-1337-important-changes
.
With specified uncommon branchType
:
gitclick sync what/SOME-1337 are you sure
Branch Name will be will be what/some-1337-are-you-sure
.
Overrides any branchType
that could be determined from Task Tags.
Shorthand Aliases
gitclick
is an alias for gitclick sync
.
glick
is an alias for gitclick
.
The following commands are all valid aliased gitclick sync
commands:
glick
gitclick
glick SOME-1337
gitclick SOME-1337
glick feature/SOME-1337
gitclick feature/SOME-1337
glick SOME-1337-important-changes
gitclick SOME-1337-important-changes
glick bug/SOME-1337-important-changes
gitclick bug/SOME-1337-important-changes
glick feature/SOME-1337 important changes
gitclick feature/SOME-1337 important changes
The same commands, but non-aliased:
gitclick sync
gitclick sync SOME-1337
gitclick sync feature/SOME-1337
gitclick sync SOME-1337-important-changes
gitclick sync bug/SOME-1337-important-changes
gitclick sync feature/SOME-1337 important changes
State
Slightly opinionated.
Currently the only command is gitclick sync
, additional commands may be added later.
Assumes the format of your Task Custom ID matches /^([a-zA-Z]+\-[\d]+)$/g
.
Why do I need this?
Short answer: You probably don't
Because everything that can be automated should be automated.
I got tired of manually copy pasting names and descriptions, maybe you are too.
If I'm automating something for my own use, I might as well share it, because others may want to do the same thing, however specific the application.
If you're reading this in the future there may be a way of doing this using native Clickup Automations.
If you're using Clickup you might find this tool useful, if not, you've wasted a lot of time reading all the way to this point of the README and should probably go do something else.
License
@zentus/gitclick is open source software licensed as MIT.