gitlab-flow

中文文档

A CLI tool to help manage the flow of developing on gitlab. The difference between this and git-flow is that gitlab-flow would operate remote(gitlab) resources like: milestone, issue, merge request and branch. Importantly, if your team using gitlab-flow together, gitlab-flow could help you to synchronize others development data by using milestoneId or interactive mode.

Installation

1. Applying a gitlab application

Before you install gitlab-flow, you need apply a gitlab application on your gitlab server.

1. Go to your gitlab Preferences -> Applications.
2. Input Name and Redirect URI (http://localhost:2333/callback).
3. Choose scopes: api, read_user, read_repository, read_registry.
4. Click Save application.
5. Copy Application Id and Secret.

2. Download or Compile binary

gitlab-flow need a gitlab application to access gitlab server, so we need to configure the application id and secret at step 4. And them are encrypted by SECRET_KEY, so you need to set SECRET_KEY to encrypt the application id and secret.

The default SECRET_KEY is aflowcli, you can change it by compiling gitlab-flow yourself.

SECRET_KEY=YOUR_SECRET_KEY \ # 8 bytes ONLY
BIN=flow2 \ # or any name you like
bash install.sh

3. Check installation

After installation, run following command to check if gitlab-flow is installed successfully.

$ which gitlab-flow
# /path/to/home/.go/bin/gitlab-flow

4. Initialize gitlab-flow

After installation, you need to configure gitlab-flow by running config init subcommand. This is an interactive command, it will ask you some questions to generate a configuration file and a sqlite database file. The home directory of gitlab-flow is ~/.gitlab-flow.

Before you run config init, you need to encrypt your APP_ID and APP_SECRET by SECRET_KEY you set in step 2.

Here is an example of encrypting APP_ID and APP_SECRET by SECRET_KEY with pseudocode.

def encrypt(appId, appSecret, secretKey):
	encrypted_appId = des_encrypt(appID, secretKey)
	encrypted_appSecret = des_encrypt(appSecret, secretKey)
	return base64_encode(encrypted_appId), base64_encode(encrypted_appSecret)

$ gitlab-flow config --global init

NOTICE: gitlab-flow will request OAuth2 credentials from your gitlab server, so you need to make sure your gitlab server is accessible.

And if you are running gitlab-flow in a headless environment, DO choose MANUAL mode on OAuth2 authorization mode.

Finally, all should be done. You can use gitlab-flow to manage your gitlab project.

How to use

This section assumes that you have installed gitlab-flow successfully.

1. Sync Project or Milestone

Before you start to manage your project branch flow, you need to make sure the project has stored in local database.

Sync milestone from gitlab server would help team partners to get the latest milestone information to local database.

# sync project
$ gitlab-flow sync project

# sync milestone interactively
$ gitlab-flow sync milestone --interact/-i

2. Start/manage a feature

After you sync project you can start/manage a feature flow as below:

# start a feature, gitlab-flow will create a branch and milestone for you.
$ gitlab-flow feature open v1.0.0 "We start a milestone v1.0.0"

# fork a issue and branch
$ gitlab-flow feature open-issue "little feature" "this is a little feature"

# finish a issue, MAKE SURE you are on the issue branch
$ gitlab-flow feature close-issue

# finish a feature, MAKE SURE you are on the feature branch
$ gitlab-flow feature release/dev/test

The hotfix flow would be similar to feature flow, you can refer to IMAGE which shows the branch flow of gitlab-flow.

Bash/Zsh Completion

gitlab-flow using urfave/cli, so you can use complete command to generate completion script.

1. Download urfave/cli completion script to a file from auto-completion
2. Copy the content of the file to your shell folders.
3. Source the file in your shell profile file.

# zsh completion for example
# download completion script
curl -L https://raw.githubusercontent.com/urfave/cli/master/autocomplete/zsh_autocomplete -o ~/.oh-my-zsh/cache/completions/gitlab-flow

# source the file in your .zshrc
echo "source ~/.oh-my-zsh/cache/completions/gitlab-flow" >> ~/.zshrc

# activate the completion
source ~/.zshrc

More help information, you can find in urfave/cli bash completion.

Access Token

❗️❗️❗️NOTICE: since 1.7.0 gitlab-flow use OAuth2 access token instead of personal access token.

!!! Before initialize gitlab-flow, you must have a custom-compiled gitlab-flow executable binary which contains appId and appSecret of gitlab application on your gitlab server.

After you initialize gitlab-flow on your machine, it will automatically request OAuth credentials from your gitlab server.

Host: The domain of your gitlab server. such as https://git.example.com

API Host: The API path to your gitlab server. such as: https://git.example.com/api/v4/. You can find it in: https://git.example.com/help/api/README.md. This page provide some example for you to request gitlab API, so you got host.

CLI Help

 ________  ___  _________  ___       ________  ________          ________ ___       ________  ___       __
|\   ____\|\  \|\___   ___\\  \     |\   __  \|\   __  \        |\  _____\\  \     |\   __  \|\  \     |\  \
\ \  \___|\ \  \|___ \  \_\ \  \    \ \  \|\  \ \  \|\ /_       \ \  \__/\ \  \    \ \  \|\  \ \  \    \ \  \
 \ \  \  __\ \  \   \ \  \ \ \  \    \ \   __  \ \   __  \       \ \   __\\ \  \    \ \  \\\  \ \  \  __\ \  \
  \ \  \|\  \ \  \   \ \  \ \ \  \____\ \  \ \  \ \  \|\  \       \ \  \_| \ \  \____\ \  \\\  \ \  \|\__\_\  \
   \ \_______\ \__\   \ \__\ \ \_______\ \__\ \__\ \_______\       \ \__\   \ \_______\ \_______\ \____________\
    \|_______|\|__|    \|__|  \|_______|\|__|\|__|\|_______|        \|__|    \|_______|\|_______|\|____________|

NAME:
   gitlab-flow - CLI tool

USAGE:
   flow2 [global options] command [command options] [arguments...]

VERSION:
   v1.8.0

DESCRIPTION:
   A tool for managing gitlab Feature/Milestone/Issue/MergeRequest as gitlab-flow.

AUTHOR:
   yeqown <[email protected]>

COMMANDS:
   config   show current configuration
   feature  managing the works in developing.
   hotfix   managing the works in hotfix.
   dash     overview of local development
   sync     synchronize resource from remote gitlab server
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --cwd path/to/file                     choose which path/to/file to load (default: /Users/yeqown/projects/opensource/gitlab-flow)
   --debug                                verbose mode (default: false)
   --project projectName, -p projectName  input projectName to locate which project should be operate. (default: gitlab-flow)
   --force-remote                         query project from remote not from local. This should be used when project name is duplicated, and could not found from local. (default: false)
   --web                                  open web browser automatically or not (default: false)
   --help, -h                             show help (default: false)
   --version, -v                          print the version (default: false)

Documents

This section records the documents of gitlab-flow, including the design, the usage, the development and the release.

Changelog

CHANGELOG.md records the changes of each version.