# gitlab-projects-issues
<!-- markdownlint-disable no-inline-html -->
[](https://pypi.org/project/gitlab-projects-issues)
[](https://pypi.org/project/gitlab-projects-issues)
[](https://pypi.org/project/gitlab-projects-issues)
[](https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues/-/blob/main/LICENSE)
<br />
[](https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues/-/commits/main/)
[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)
[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)
[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)
[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)
[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)
<br />
[](https://github.com/pre-commit/pre-commit)
[](https://commitizen-tools.github.io/commitizen/)
[](https://radiandevcore.gitlab.io/tools/gcil)
[](https://radiandevcore.gitlab.io/tools/pre-commit-crocodile)
Generate GitLab project issues and milestones statistics automatically
**Documentation:** <https://radiandevcore.gitlab.io/tools/gitlab-projects-issues>
**Package:** <https://pypi.org/project/gitlab-projects-issues/>
---
## Purpose
This tool can automatically generate issues and milestones statistics,
by analyzing project's issues, detecting milestones and assignees.
If issues without time estimations are found, `~?` will be shown before time outputs.
Milestone statistics will automatically be injected in the milestone description,
with a markdown table of assignees, timings, progress and issues total.
The following step is required before using the tool:
- The GitLab user tokens must be created with an `api` scope (a short expiration date is recommended)
---
## Examples
<!-- prettier-ignore-start -->
```bash
# Show the helper menu
gitlab-projects-issues
# Inject milestones statistics into milestones' description
gitlab-projects-issues --milestones-statistics 'https://gitlab.com/group/project'
# Inject milestones statistics into milestones' description (with default 20h time per unestimated issues)
gitlab-projects-issues --milestones-statistics --default-estimate '20' 'https://gitlab.com/group/project'
```
<!-- prettier-ignore-end -->
---
<span class="page-break"></span>
## Outputs
Milestones statistics will automatically be added to each milestone's description.
The following example shows how milestones statistics may look on a project:
> ## Milestone statistics - MILESTONE NAME
>
> | Assignees | Issues | Estimated | Spent | Remaining | Progress |
> |-----------|--------|-----------|-------|-----------|----------|
> | **Without assignee** | 10 | 18d | 18d | / | ██████████ 100.00% |
> | **User ONE** | 22 | 42d | 5d | 37d | █▂▁▁▁▁▁▁▁▁ 11.90% |
> | **User TWO** | 29 | 50d 2h | 20d 6h | 29d 4h | ████▂▁▁▁▁▁ 41.29% |
> | **User THREE** | 7 | 9d 2h | 3d 4h | 5d 6h | ███▅▁▁▁▁▁▁ 37.84% |
> | **User FOUR** | 6 | 21d | / | 21d | ▁▁▁▁▁▁▁▁▁▁ 0.00% |
> | _**Total**_ | _74_ | _135d 4h_ | _47d 2h_ | 93d 2h | _███▄▁▁▁▁▁▁ 34.87%_ |
>
> _Last update using gitlab-projects-issues : 2024-06-01 19:38:48 UTC_
---
<span class="page-break"></span>
## Usage
<!-- prettier-ignore-start -->
<!-- readme-help-start -->
```yaml
usage: gitlab-projects-issues [-h] [--version] [--no-color] [--update-check] [--settings] [--set GROUP KEY VAL]
[-c FILES] [--dump] [--default-estimate ESTIMATE] [--exclude-closed-issues]
[--milestone MILESTONE] [--milestones-statistics] [--exclude-closed-milestones] [--]
[url_path]
gitlab-projects-issues: Generate GitLab project issues and milestones statistics automatically
internal arguments:
-h, --help # Show this help message
--version # Show the current version
--no-color # Disable colors outputs with 'NO_COLOR=1'
# (or default settings: [themes] > no_color)
--update-check # Check for newer package updates
--settings # Show the current settings path and contents
--set GROUP KEY VAL # Set settings specific 'VAL' value to [GROUP] > KEY
# or unset by using 'UNSET' as 'VAL'
credentials arguments:
-c FILES, --config FILES # Python GitLab configuration files (default: PYTHON_GITLAB_CFG environment)
common arguments:
--dump # Dump Python objects of projects
issues arguments:
--default-estimate ESTIMATE # Default issue time estimate if none providedin hours (default: 8)
--exclude-closed-issues # Exclude issues in closed state
milestones arguments:
--milestone MILESTONE # Use a specific milestone by name, by ID, or "None"
--milestones-statistics # Inject milestones statistics into milestones' description
--exclude-closed-milestones # Exclude milestones in closed state
positional arguments:
-- # Positional arguments separator (recommended)
url_path # GitLab project path URL
environment variables:
GITLAB_TOKEN # GitLab API token environment variable
CI_JOB_TOKEN # GitLab CI job token environment variable (CI only)
```
<!-- readme-help-stop -->
<!-- prettier-ignore-end -->
---
<span class="page-break"></span>
## Python GitLab configuration file
`gitlab-projects-issues` uses the same configuration files as the `python-gitlab` API,
holding domains, URL and private tokens credentials for the GitLab instances.
The default user configuration file can be created at `~/.python-gitlab.cfg`.
The `-c` or `--config` parameters can provide specific configuration files,
otherwise the `PYTHON_GITLAB_CFG` environment variable can be used.
**Example `~/.python-gitlab.cfg` configuration file:**
```ini title="~/.python-gitlab.cfg"
[global]
default = gitlab.com
ssl_verify = true
timeout = 5
[gitlab.com]
url = https://gitlab.com
private_token = glpat-...
[gitlab.local.dev]
url = https://gitlab.local.dev
private_token = glpat-...
[gitlab.private.dev:4243]
url = https://gitlab.private.dev:4243
private_token = glpat-...
ssl_verify = /usr/local/share/ca-certificates/gitlab.private.dev.crt
```
**`python-gitlab` configuration files documentation:** [Getting started with the CLI / Configuration files](https://python-gitlab.readthedocs.io/en/stable/cli-usage.html#configuration-files)
---
<span class="page-break"></span>
## Userspace available settings
`gitlab-projects-issues` creates a `settings.ini` configuration file in a userspace folder.
For example, it allows to disable the automated updates daily check (`[updates] > enabled`)
The `settings.ini` file location and contents can be shown with the following command:
```bash
gitlab-projects-issues --settings
```
---
## Environment available configurations
`gitlab-projects-issues` uses `colored` for colors outputs.
If colors of both outputs types do not match the terminal's theme,
an environment variable `NO_COLOR=1` can be defined to disable colors.
---
<span class="page-break"></span>
## Dependencies
- [colored](https://pypi.org/project/colored/): Terminal colors and styles
- [python-gitlab](https://pypi.org/project/python-gitlab/): A python wrapper for the GitLab API
- [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages
- [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI
---
## References
- [commitizen](https://pypi.org/project/commitizen/): Simple commit conventions for internet citizens
- [git-cliff](https://github.com/orhun/git-cliff): CHANGELOG generator
- [gitlab-release](https://pypi.org/project/gitlab-release/): Utility for publishing on GitLab
- [gcil](https://radiandevcore.gitlab.io/tools/gcil): Launch .gitlab-ci.yml jobs locally
- [mkdocs](https://www.mkdocs.org/): Project documentation with Markdown
- [mkdocs-exporter](https://adrienbrignon.github.io/mkdocs-exporter/): Exporter plugin for mkdocs documentation
- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/): Material theme for mkdocs documentation
- [mypy](https://pypi.org/project/mypy/): Optional static typing for Python
- [pre-commit](https://pre-commit.com/): A framework for managing and maintaining pre-commit hooks
- [pre-commit-crocodile](https://radiandevcore.gitlab.io/tools/pre-commit-crocodile): Git hooks intended for developers using pre-commit
- [PyPI](https://pypi.org/): The Python Package Index
- [twine](https://pypi.org/project/twine/): Utility for publishing on PyPI
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues",
"name": "gitlab-projects-issues",
"maintainer": null,
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3",
"maintainer_email": null,
"keywords": "gitlab projects issues milestones",
"author": "Adrian DC",
"author_email": "radian.dc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dd/63/5adc5759774ce9b24bc3a4832d5e18b18e9eb498248734d01fb805336996/gitlab_projects_issues-3.1.0.tar.gz",
"platform": null,
"description": "# gitlab-projects-issues\n\n<!-- markdownlint-disable no-inline-html -->\n\n[](https://pypi.org/project/gitlab-projects-issues)\n[](https://pypi.org/project/gitlab-projects-issues)\n[](https://pypi.org/project/gitlab-projects-issues)\n[](https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues/-/blob/main/LICENSE)\n<br />\n[](https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues/-/commits/main/)\n[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)\n[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)\n[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)\n[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)\n[](https://sonarcloud.io/dashboard?id=RadianDevCore_gitlab-projects-issues)\n<br />\n[](https://github.com/pre-commit/pre-commit)\n[](https://commitizen-tools.github.io/commitizen/)\n[](https://radiandevcore.gitlab.io/tools/gcil)\n[](https://radiandevcore.gitlab.io/tools/pre-commit-crocodile)\n\nGenerate GitLab project issues and milestones statistics automatically\n\n**Documentation:** <https://radiandevcore.gitlab.io/tools/gitlab-projects-issues> \n**Package:** <https://pypi.org/project/gitlab-projects-issues/>\n\n---\n\n## Purpose\n\nThis tool can automatically generate issues and milestones statistics, \nby analyzing project's issues, detecting milestones and assignees.\n\nIf issues without time estimations are found, `~?` will be shown before time outputs.\n\nMilestone statistics will automatically be injected in the milestone description, \nwith a markdown table of assignees, timings, progress and issues total.\n\nThe following step is required before using the tool:\n\n- The GitLab user tokens must be created with an `api` scope (a short expiration date is recommended)\n\n---\n\n## Examples\n\n<!-- prettier-ignore-start -->\n\n```bash\n# Show the helper menu\ngitlab-projects-issues\n\n# Inject milestones statistics into milestones' description\ngitlab-projects-issues --milestones-statistics 'https://gitlab.com/group/project'\n\n# Inject milestones statistics into milestones' description (with default 20h time per unestimated issues)\ngitlab-projects-issues --milestones-statistics --default-estimate '20' 'https://gitlab.com/group/project'\n```\n\n<!-- prettier-ignore-end -->\n\n---\n\n<span class=\"page-break\"></span>\n\n## Outputs\n\nMilestones statistics will automatically be added to each milestone's description.\n\nThe following example shows how milestones statistics may look on a project:\n\n> ## Milestone statistics - MILESTONE NAME\n>\n> | Assignees | Issues | Estimated | Spent | Remaining | Progress |\n> |-----------|--------|-----------|-------|-----------|----------|\n> | **Without assignee** | 10 | 18d | 18d | / | \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588 100.00% |\n> | **User ONE** | 22 | 42d | 5d | 37d | \u2588\u2582\u2581\u2581\u2581\u2581\u2581\u2581\u2581\u2581 11.90% |\n> | **User TWO** | 29 | 50d 2h | 20d 6h | 29d 4h | \u2588\u2588\u2588\u2588\u2582\u2581\u2581\u2581\u2581\u2581 41.29% |\n> | **User THREE** | 7 | 9d 2h | 3d 4h | 5d 6h | \u2588\u2588\u2588\u2585\u2581\u2581\u2581\u2581\u2581\u2581 37.84% |\n> | **User FOUR** | 6 | 21d | / | 21d | \u2581\u2581\u2581\u2581\u2581\u2581\u2581\u2581\u2581\u2581 0.00% |\n> | _**Total**_ | _74_ | _135d 4h_ | _47d 2h_ | 93d 2h | _\u2588\u2588\u2588\u2584\u2581\u2581\u2581\u2581\u2581\u2581 34.87%_ |\n>\n> _Last update using gitlab-projects-issues : 2024-06-01 19:38:48 UTC_\n\n---\n\n<span class=\"page-break\"></span>\n\n## Usage\n\n<!-- prettier-ignore-start -->\n<!-- readme-help-start -->\n\n```yaml\nusage: gitlab-projects-issues [-h] [--version] [--no-color] [--update-check] [--settings] [--set GROUP KEY VAL]\n [-c FILES] [--dump] [--default-estimate ESTIMATE] [--exclude-closed-issues]\n [--milestone MILESTONE] [--milestones-statistics] [--exclude-closed-milestones] [--]\n [url_path]\n\ngitlab-projects-issues: Generate GitLab project issues and milestones statistics automatically\n\ninternal arguments:\n -h, --help # Show this help message\n --version # Show the current version\n --no-color # Disable colors outputs with 'NO_COLOR=1'\n # (or default settings: [themes] > no_color)\n --update-check # Check for newer package updates\n --settings # Show the current settings path and contents\n --set GROUP KEY VAL # Set settings specific 'VAL' value to [GROUP] > KEY\n # or unset by using 'UNSET' as 'VAL'\n\ncredentials arguments:\n -c FILES, --config FILES # Python GitLab configuration files (default: PYTHON_GITLAB_CFG environment)\n\ncommon arguments:\n --dump # Dump Python objects of projects\n\nissues arguments:\n --default-estimate ESTIMATE # Default issue time estimate if none providedin hours (default: 8)\n --exclude-closed-issues # Exclude issues in closed state\n\nmilestones arguments:\n --milestone MILESTONE # Use a specific milestone by name, by ID, or \"None\"\n --milestones-statistics # Inject milestones statistics into milestones' description\n --exclude-closed-milestones # Exclude milestones in closed state\n\npositional arguments:\n -- # Positional arguments separator (recommended)\n url_path # GitLab project path URL\n\nenvironment variables:\n GITLAB_TOKEN # GitLab API token environment variable\n CI_JOB_TOKEN # GitLab CI job token environment variable (CI only)\n```\n\n<!-- readme-help-stop -->\n<!-- prettier-ignore-end -->\n\n---\n\n<span class=\"page-break\"></span>\n\n## Python GitLab configuration file\n\n`gitlab-projects-issues` uses the same configuration files as the `python-gitlab` API, \nholding domains, URL and private tokens credentials for the GitLab instances.\n\nThe default user configuration file can be created at `~/.python-gitlab.cfg`.\n\nThe `-c` or `--config` parameters can provide specific configuration files, \notherwise the `PYTHON_GITLAB_CFG` environment variable can be used.\n\n**Example `~/.python-gitlab.cfg` configuration file:**\n\n```ini title=\"~/.python-gitlab.cfg\"\n[global]\ndefault = gitlab.com\nssl_verify = true\ntimeout = 5\n\n[gitlab.com]\nurl = https://gitlab.com\nprivate_token = glpat-...\n\n[gitlab.local.dev]\nurl = https://gitlab.local.dev\nprivate_token = glpat-...\n\n[gitlab.private.dev:4243]\nurl = https://gitlab.private.dev:4243\nprivate_token = glpat-...\nssl_verify = /usr/local/share/ca-certificates/gitlab.private.dev.crt\n```\n\n\n**`python-gitlab` configuration files documentation:** [Getting started with the CLI / Configuration files](https://python-gitlab.readthedocs.io/en/stable/cli-usage.html#configuration-files)\n\n---\n\n<span class=\"page-break\"></span>\n\n## Userspace available settings\n\n`gitlab-projects-issues` creates a `settings.ini` configuration file in a userspace folder.\n\nFor example, it allows to disable the automated updates daily check (`[updates] > enabled`)\n\nThe `settings.ini` file location and contents can be shown with the following command:\n\n```bash\ngitlab-projects-issues --settings\n```\n\n---\n\n## Environment available configurations\n\n`gitlab-projects-issues` uses `colored` for colors outputs.\n\nIf colors of both outputs types do not match the terminal's theme, \nan environment variable `NO_COLOR=1` can be defined to disable colors.\n\n---\n\n<span class=\"page-break\"></span>\n\n## Dependencies\n\n- [colored](https://pypi.org/project/colored/): Terminal colors and styles\n- [python-gitlab](https://pypi.org/project/python-gitlab/): A python wrapper for the GitLab API\n- [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages\n- [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI\n\n---\n\n## References\n\n- [commitizen](https://pypi.org/project/commitizen/): Simple commit conventions for internet citizens\n- [git-cliff](https://github.com/orhun/git-cliff): CHANGELOG generator\n- [gitlab-release](https://pypi.org/project/gitlab-release/): Utility for publishing on GitLab\n- [gcil](https://radiandevcore.gitlab.io/tools/gcil): Launch .gitlab-ci.yml jobs locally\n- [mkdocs](https://www.mkdocs.org/): Project documentation with Markdown\n- [mkdocs-exporter](https://adrienbrignon.github.io/mkdocs-exporter/): Exporter plugin for mkdocs documentation\n- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/): Material theme for mkdocs documentation\n- [mypy](https://pypi.org/project/mypy/): Optional static typing for Python\n- [pre-commit](https://pre-commit.com/): A framework for managing and maintaining pre-commit hooks\n- [pre-commit-crocodile](https://radiandevcore.gitlab.io/tools/pre-commit-crocodile): Git hooks intended for developers using pre-commit\n- [PyPI](https://pypi.org/): The Python Package Index\n- [twine](https://pypi.org/project/twine/): Utility for publishing on PyPI\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Generate GitLab project issues and milestones statistics automatically",
"version": "3.1.0",
"project_urls": {
"Bug Reports": "https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues/-/issues",
"Changelog": "https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues/blob/main/CHANGELOG.md",
"Documentation": "https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues#gitlab-projects-issues",
"Homepage": "https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues",
"Source": "https://gitlab.com/RadianDevCore/tools/gitlab-projects-issues",
"Statistics": "https://pypistats.org/packages/gitlab-projects-issues"
},
"split_keywords": [
"gitlab",
"projects",
"issues",
"milestones"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b6a0d1d1d6a8be2551a5b5e241331193f77c73a429ef4d99ce8e54b1b933bcd3",
"md5": "c8d41408dd0a4dd9ae34936ae9e8fd3d",
"sha256": "9981a0d57f2e2b00b36e91cb71abf6b721276488508eae04f925a4461e202238"
},
"downloads": -1,
"filename": "gitlab_projects_issues-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8d41408dd0a4dd9ae34936ae9e8fd3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3",
"size": 28253,
"upload_time": "2024-10-28T22:17:16",
"upload_time_iso_8601": "2024-10-28T22:17:16.958391Z",
"url": "https://files.pythonhosted.org/packages/b6/a0/d1d1d6a8be2551a5b5e241331193f77c73a429ef4d99ce8e54b1b933bcd3/gitlab_projects_issues-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dd635adc5759774ce9b24bc3a4832d5e18b18e9eb498248734d01fb805336996",
"md5": "50875576e1b93454c98aa45cb11c3bdd",
"sha256": "6d3e4c408f4d4f2d4e735357f3dd6d2f0812f2edccbdb6a056de282ed9075beb"
},
"downloads": -1,
"filename": "gitlab_projects_issues-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "50875576e1b93454c98aa45cb11c3bdd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3",
"size": 66207,
"upload_time": "2024-10-28T22:17:18",
"upload_time_iso_8601": "2024-10-28T22:17:18.257151Z",
"url": "https://files.pythonhosted.org/packages/dd/63/5adc5759774ce9b24bc3a4832d5e18b18e9eb498248734d01fb805336996/gitlab_projects_issues-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 22:17:18",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "RadianDevCore",
"gitlab_project": "tools",
"lcname": "gitlab-projects-issues"
}
JSON