Welcome to Labelord’s documentation!¶

INTRO¶

This is a command-line application with Flask web interface. It allows to manage labels from GitHub issues. Goal of project is to make it easy to manage labels for multiple repositories and not to create same labels for all repositories.

Application can list all repositories or all labels of issues in given repository. Application can update or replace labels with labels from another source. Finally application can run a Flask web interface.

Application is installed as Python module. For examples how to run commands see USAGE or TEST.

Application need a GitHub API token for connection to GitHub. This token can be used to access the GitHub API and allows you to see some details of repositories. Manual for obtaining this token is in section GitHub API token. Web interface need a webhook for connection to GitHub. Manual for obtaining this webhook is in section GitHub webhook secret.

Part of application can be set by configuration file or options. Config file is writen in INI format. See more details in Configuration file. Details about options are in Options.

INSTALL¶

Labelord application is install as Python module. Module can be downloaded from PyPi https://test.pypi.org/project/labelord-stejsle1/ or from GitHub repository https://github.com/stejsle1/labelord/releases as latest release.

After you download it you can install it.

Move to folder with extract files. To make a module from file run:

python3 setup.py sdist

It will make a dist folder with distribution. To install module run:

python3 -m pip install dist/Labelord-Version.tar

Command will automatically install required modules.

Now the Labelord module is install and you can run application:

# For help type:
python3 -m labelord
# or
labelord

For running commands type (for more information ses USAGE):

python3 -m labelord [command options]
# or
labelord [command options]

For details about configuration see CONFIG.

USAGE¶

If Labelord module is installed you can start to use it.

All commands can be run by typing:

python3 -m labelord [command options]
# or
labelord [command options]

All commands and its options are explained below.

List repos¶

This command print out all repositories according to given token.

list_repos

This code end with error code because no GitHub token was inserted.

If you want to set a configuration file, type:

list_repos -c YourConfigFile.cfg
# or
list_repos --config YourConfigFile.cfg

Token can be also insert via option:

list_repos -t YourToken
# or
list_repos --token YourToken

Warning

Be sure your token can’t be copied or saved in some way by unauthorized person. Secure your confidential data.

List labels¶

This command print out all label from given repository.

list_labels MyNick/MyRepository

This code end with error code because no GitHub token was inserted.

If you want to set a configuration file, type:

list_labels -c YourConfigFile.cfg MyNick/MyRepository
# or
list_labels --config YourConfigFile.cfg MyNick/MyRepository

Token can be also insert via option:

list_labels -t YourToken MyNick/MyRepository
# or
list_labels --token YourToken MyNick/MyRepository

Warning

Be sure your token can’t be copied or saved in some way by unauthorized person. Secure your confidential data.

Run¶

This command run a label changes. To run it you must decided if you want to update labels or replace labels.

Token can be provided same ways as in commands list_repos and list_labels - by config file and by option. To save space thid documentation will be working with configfile-way.

Warning

Be sure your token can’t be copied or saved in some way by unauthorized person. Secure your confidential data.

Update¶

To update label means if your changing repository missing some label, then label will be inserted. If you have some labels which are not in template repository, this labels will be keeped in. Same labels are keep in.

To update labels run:

run update -c YourConfigFile.cfg

If repositories and labels or template repository are set in config file, then this command will make changes fine.

If repositories are not set in config file, you can set to run this changes to all repositories from command list_repos by typing option --all_repos:

run update -c YourConfigFile.cfg --all-repos
# or
run update -c YourConfigFile.cfg -a

If nor labels nor template repository are not set in config file, you can set template repository by option --template-repo:

run update -c YourConfigFile.cfg --template-repo YourRepo
# or
run update -c YourConfigFile.cfg -r

If you don’t want to make change and run it to check what would be changed, run dry_run:

run update -c YourConfigFile.cfg --dry-run
# or
run update -c YourConfigFile.cfg -d

Command can be run in verbose or quiet mode:

run update -c YourConfigFile.cfg --verbose
# or
run update -c YourConfigFile.cfg -v

run update -c YourConfigFile.cfg --quiet
# or
run update -c YourConfigFile.cfg -q

Replace¶

To replace label means if your changing repository missing some label, then label will be inserted. If you have some labels which are not in template repository, this labels will be deleted. Same labels are keep in.

To replace labels run:

run replace -c YourConfigFile.cfg

If repositories and labels or template repository are set in config file, then this command will make changes fine.

If repositories are not set in config file, you can set to run this changes to all repositories from command list_repos by typing option --all_repos:

run replace -c YourConfigFile.cfg --all-repos
# or
run replace -c YourConfigFile.cfg -a

If nor labels nor template repository are not set in config file, you can set template repository by option --template-repo:

run replace -c YourConfigFile.cfg --template-repo YourRepo
# or
run replace -c YourConfigFile.cfg -r

If you don’t want to make change and run it to check what would be changed, run dry_run:

run replace -c YourConfigFile.cfg --dry-run
# or
run replace -c YourConfigFile.cfg -d

Command can be run in verbose or quiet mode:

run replace -c YourConfigFile.cfg --verbose
# or
run replace -c YourConfigFile.cfg -v

run replace -c YourConfigFile.cfg --quiet
# or
run replace -c YourConfigFile.cfg -q

Run server¶

This command run a server - Flask web interface. This command need to has set an envitonment variable LABELORD_CONFIG. This variable contains config file name with configuration (token, webhook secret, ...).

To run a server, type:

run_server

In this case server will run on 127.0.0.1 on port 5000 (default values). If you want to run server on different host or port, run command:

run_server --host 146.13.306.124 --port 5001
# or
run_server -h 146.13.306.124 -p 5001

You can run server in debug mode:

run_server --debug
# or
run_server -d

This mode can be also triggered by environment variable FLASK_DEBUG with value true.

CONFIG¶

Configuration can be set by configuration file or options.

Configuration file¶

General input to application is configuration file. This file is written in INI format. File is set by option -c/–config. Default value is ‘./config.cfg’.

File have to contain section ‘github’, where is placed GitHub token and webhook secret.

[github]
token = YourToken
webhook_secret = YourWebhook

Next acceptable sections are ‘repos’, ‘labels’ and ‘others’. Section ‘repos’ defines repositories which will be changed. In section will be list of repositories and flag ‘on/off’ for making or not making changes on this repository. List of repositories can be empty.

[repos]
stejsle1/lab01 = on
stejsle1/labelord = on
stejsle1/wator = off

Section ‘labels’ defines list of labels which will be insert in repository. Every line in section is a pair of name and color. List can be empty.

[labels]
Error = FF0000
Important = 112233

Section ‘others’ defines a template repository. This means labels will be change to be same as in template repository.

[others]
template-repo = stejsle1/wator

GitHub API token¶

To obtain this token log in GitHub. Open a ‘Personal setting’, click to ‘Developer settings’. In section ‘Personal access tokens’ click to ‘Generate new token’. It opens a new page with form. Fill a token description and mark ‘public-repo’. This option allows to make changes with repositories. Save this token to personal secret place.

Warning

Never place this token to GitHub or another public place!

GitHub webhook secret¶

To be sure a request is really from GitHub there is a option to add a secret item into webhook. Then application reads a header ‘X-Hub-Signature’ and checks if this secret was used to create request header. If do then request can be trusted.

To set webhook open your repository and click on ‘Settings’. On left menu click on ‘Webhooks’. On ritgh side click on ‘Add webhook’. On new page fill a form and hit ‘Add webhook’.

Options¶

For all settings in config file there is a option.

-c/–config [name]

Set config file.

-t/–token [token]

Set token.

-r/–template-repo [repo]

Set template repository (labels will be change to same ones as in this repository).

-a/–all-repos

Changes will be taken in all repos from request ‘list_repos’.

-d/–dry-run

Set ‘dry run’ (application don’t make real changes).

-v/–verbose

Set verbose mode.

-q/–quiet

Set quiet mode (no output).

-h/–host [host]

Set hostname for web interface (default 127.0.0.1).

-p/–port [port]

Set port for web interface (default 5000).

-d/–debug

Set debug mode.

Environment variables¶

Last option to set configuration is by environment variables. There is a few variables which are supported.

GITHUB_TOKEN

Set token. Example: GITHUB_TOKEN=’YourToken’

LABELORD_CONFIG

Set config file for web interface. Example: LABELORD_CONFIG=’./config.cfg’

FLASK_DEBUG

Set debug mode for web interface. Exaplme: FLASK_DEBUG=true

API¶

labelord¶

Open config file, set session and context.

Main function.

param:	`ctx` Context, for Click
param:	`config` Config file
param:	`token` Token
return:	`None`

labelord [OPTIONS] COMMAND [ARGS]...

Options

-h, --help¶: Show this message and exit.

--version¶: Show the version and exit.

-c, --config <config>¶: Config file

-t, --token <token>¶: Token

list_labels¶

List labels.

Check if token provided. If do get all labels from repository and print them.

param:	`ctx` Context, for Click
param:	`repository` Repository from which labels will be listed
param:	`token` Token
param:	`tenv` Token if set by environment variable
return:	`None`

labelord list_labels [OPTIONS] REPOSITORY

Options

-t, --token <token>¶: Token

--tenv <tenv>¶

Arguments

REPOSITORY¶: Required argument

Environment variables

GITHUB_TOKEN¶: Provide a default for --tenv

list_repos¶

List repos.

Check if token provided. I do get repositories and print them.

param:	`ctx` Context, for Click
param:	`token` Token
param:	`tenv` Token if set by environment variable
return:	`None`

labelord list_repos [OPTIONS]

Options

-t, --token <token>¶: Token

--tenv <tenv>¶

Environment variables

GITHUB_TOKEN¶: Provide a default for --tenv

run¶

Run a labels update/replace.

Check if token provided. If do get labels (as template ones and changable ones) and do the magic - change them the way that all repositories has same (template) labels (dont forget update/replace mode).

param:	`ctx` Context, for Click
param:	`mode` Mode of run [update, replace]
param:	`template_repo` Template repositary from which labels will be using
param:	`all_repos` Flag, if changes will be taken in all repositaries from `list_repos` command
param:	`dry_run` Flag, if changes will be canceled
param:	`verbose` Flag, set verbose mode
param:	`quiet` Flag, set quiet mode (no output)
param:	`token` Token
param:	`tenv` Token if set by environment variable
return:	`None`

labelord run [OPTIONS] MODE

Options

-r, --template-repo <template_repo>¶: Add a template repo.

-a, --all-repos¶: All available repos.

-d, --dry-run¶: Dry run

-v, --verbose¶: Verbose mode

-q, --quiet¶: Quiet mode

-t, --token <token>¶: Token

--tenv <tenv>¶

Arguments

MODE¶: Required argument

Environment variables

GITHUB_TOKEN¶: Provide a default for --tenv

run_server¶

Run a server with Flask app.

param:	`ctx` Context, from Click
param:	`host` Hostname for interface (default 127.0.0.1)
param:	`port` Port for interface (default 5000)
param:	`debug` Flag, set debug mode
return:	`None`

labelord run_server [OPTIONS]

Options

-h, --host <host>¶: Host address

-p, --port <port>¶: Port

-d, --debug¶: Debug mode

Environment variables

FLASK_DEBUG¶: Provide a default for -d

labelord.labelord.main()[source]¶

labelord.setupfile.printextra(level, text, label, err)[source]¶

Print output.

Param:	`level` Indicator of quiet/verbose/normal mode
Param:	`text` String to print out
Param:	`label` Label name
Param:	`err` Flag, if error occurs or dry-run
Returns:	`None`

labelord.setupfile.setup(session, token)[source]¶

Set session - set token into request header.

Param:	`session` Session for comunication with GitHub
Param:	`token` Set token to header Authentization
Returns:	`session`

class labelord.web.LabelordWeb(*args, **kwargs)[source]¶

Bases: flask.app.Flask

Flask web interface class

inject_session(session)[source]¶

Session setting.

Param:	`self` Context
Param:	`session` Session for comunication with GitHub
Returns:	`None`

reload_config()[source]¶

Config setting.

Open config file and set congiguration (token, webhook secret, ...), set a self context.

Param:	`self` Context
Returns:	`None`

labelord.web.convert_str_to_link(text)[source]¶

Convert the repo name to link, assistant function for GET requests.

Param:	`text` String - repository name - to convert
Returns:	`Link`

labelord.web.get()[source]¶

GET requests

Handle GET requests - print repositories and link to repositories.

Returns:	`render template` Rendering page

labelord.web.post()[source]¶

POST requests

Handle POST requests - chech if request from GitHub, if do make command according to POST request and send response.

Returns:	`response`

TEST¶

Documentation can test some labelord function to see how they works.

For example it checks function `convert_time(*string)`’ for printing link to GitHub repository:

>>> convert_str_to_link("stejsle1/lab01")
'https://github.com/stejsle1/lab01'

More information about function `convert_time(*string)`’ is in API

Next example shows how to print messages. In case application in verbose mode add label 'Need vacation' with color 'FFFFFF' into repository 'stejsle1/myNewSummerRepo':

printextra(2, "stejsle1/myNewSummerRepo; Need vacation; FFFFFF", "ADD", 0)

it prints:

[ADD][SUC] stejsle1/myNewSummerRepo; Need vacation; FFFFFF

In case application in normal mode update label 'Unbreakable' with color '123456' to color '654321' into repository 'stejsle1/myNewWinterRepo' it prints nothing because application in normal mode prints only errors to stderr and summary to stdout.

So if same command ends with error 422 - Validation Failed:

printextra(1, "stejsle1/myNewWinterRepo; Unbreakable; 654321; 422 - Validation Failed", "UPD", 1)

it prints out:

ERROR: UPD; stejsle1/myNewWinterRepo; Unbreakable; 654321; 422 - Validation Failed

In normal mode module prints out a summary (with 2 errors) message:

>>> printextra(4+1, str(2) + ' error(s) in total, please check log above', '', 1)
SUMMARY: 2 error(s) in total, please check log above

Flawless case of summary report in verbose mode:

>>> printextra(4+2, str(3) + ' repo(s) updated successfully', '', 0)
[SUMMARY] 3 repo(s) updated successfully

In quiet mode application prints nothing, neither summary message.