sudoblark.python.github-cli

A CLI to interact with GitHub, intended to be used for CI/CD operations.
· Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Technical Documentation
5. Testing
6. CI/CD
7. License
8. Acknowledgments

About The Project

This is a really basic CLI that wraps around sudoblark.python.core to provide useful GitHub CLI functionality, intended for usage within CI/CD platforms but also usable elsewhere.

The live source of documentation sits here.

(back to top)

Built With

• Library
  • Python 3.10
• Testing and quality control
  • flake8-pyproject
  • flake8
  • pytest
  • coverage
  • unittest
• Packaging
  • pyproject.toml

(back to top)

Getting Started

The below are instructions for how to develop the CLI, for instructions on how to install see the Usage section instead.

Prerequisites

These installation instructions are targeted for MacOS.

• Python3.10

  brew install python@3.10

• Poetry

  python3.10 -m venv venv
  source venv/bin/activate
  pip install -U pip setuptools
  pip install poetry

Installation

Assume a local virtual environment, and poetry, are setup as per the Prerequisites then installation is simply:

poetry install

Which you may verify via:

sudoblark-github-cli --help

(back to top)

Usage

Install from PyPi:

pip install sudoblark-github-cli

And off you go. Run --help commands are available at all levels for further information, get started by simply running:

sudoblark-github-cli --help

(back to top)

Technical Documentation

mkdocs is used in order to auto-generation documentation. It is configured via the docs/mkdocs.yml file and - for the most part - doesn't need to be altered.

In order to generation a local web server of documentation:

mkdocs serve

However, it should be noted that live versioned documentation is produced via the appropriate workflow as per the CI/CD section of this document.

(back to top)

Testing

PyTest is used to test the behaviour of our CLI, whilst coverage uses these tests to generate a code coverage report.

Tests may be simply run via the following command:

poetry run coverage run -m pytest
poetry run coverage report
poetry run coverage html

However, these are executed for you automatically on a commit to an open pull request as well.

NOTE: All scenarios require a valid GITHUB_TOKEN environment variable to be present

(back to top)

CI/CD

GitHub Actions is used for all CI/CD activities. We give a brief outline of what each pipeline does below.

Pipeline	Triggers	Description
commit-to-pull-request.yaml	Commit on a pull request	Run Python quality checks
release.yaml	When a release is published	Builds and publishes docs and pypi package

(back to top)

License

Distributed under the project_license. See LICENSE.txt for more information.

(back to top)

Acknowledgments

• Command line icons created by PIXARTIST - Flaticon for the wonderful logo