Metadata-Version: 2.1
Name: badges-gitlab
Version: 0.5.0
Summary: Generate badges for Gitlab Projects in Public and Private Repositories
Home-page: https://gitlab.com/felipe_public/badges-gitlab
Author: Felipe P. Silva
Author-email: felipefoz@gmail.com
License: MIT License
Project-URL: Bug Tracker, https://gitlab.com/felipe_public/badges-gitlab/-/issues
Description: # Badges Gitlab
        
        This project was created to generate badges for Gitlab in CI jobs, mainly for private repositories where
        other common methods are not available (direct API Calls, shields.io, etc...).
        
        By default, Gitlab supports only two types of badges: pipeline and test coverage.
        
        These badges are better detailed at: [https://docs.gitlab.com/ee/user/project/badges.html]().
            
        ## Requirements
        
        For using this package, it will also install these packages and their dependencies:
        - Python Gitlab API
        - Anybadge
        - Iso8601
        - xmltodict
        
        ## Usage 
        
        ### Common Usage
        
        Install this package from pip.
        
        ```code
        $ pip install badges-gitlab
        $ badges-gitlab -h 
        usage: badges-gitlab [-h] [-p TEXT] [-t TEXT] [--junit-xml TEXT] [-V]
        
        Generate Gitlab Badges using JSON files and API requests. Program version v0.0.0.
        
        optional arguments:
          -h, --help            show this help message and exit
          -p TEXT, --path TEXT  path where json and badges files will be generated/located (default: ./public/badges/)
          -t TEXT, --token TEXT specify the private-token in command line (default: ${PRIVATE_TOKEN})
          --junit-xml TEXT      specifies the path of a JUnit XML file for parsing the test results
          -V, --version         returns the package version
        
        ```
        This package was intended to be used in CI jobs, but if you to test locally, you must point a 
        folder with the json files in the format used by [shields.io endpoint](https://shields.io/endpoint).
        ```json
        {
          "schemaVersion": 1,
          "label": "hello",
          "message": "sweet world",
          "color": "orange"
        }
        ```
        
        ### Gitlab CI YAML Pipeline Job Example
        
        Below it is an example of a job running at the end of the pipeline in the default branch (main) 
        and using cache for job optimization.
        
        To ensure all possible badges are generated, include the [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) 
        as an environment variable direct into the .gitlab-ci.yml or 
        in the [CI/CD Variables configuration](https://docs.gitlab.com/ee/ci/variables/).
        
        ```yaml
        badges:
          image: python:3.9
          stage: badges
          variables:
            PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
            PRIVATE_TOKEN: $ACCESS_TOKEN
          cache:
            key: badges
            paths:
              - .cache/pip
              - venv/
          before_script:
             - python -V        
             - pip install virtualenv
             - virtualenv venv
             - source venv/bin/activate
          script:
             - pip install badges-gitlab
             - badges-gitlab -V
             - badges-gitlab
          artifacts:
            when: always
            paths:
              - public/badges/*.svg
            expire_in: 3 months
          rules:
            - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
              when: always
              allow_failure: true
         ```
        
        As the badges are generated only during this job, and if you want to make sure there are available for some 
        time. So, adjust the expiration of the artifacts accordingly.
        
        ### Schedule Pipelines
        
        Some badges have dynamic data and are generated only during this job, and the data can be outdated.
        If you don't want to use third party APIs all the time to generate the badges (sometimes these APIs fail), you could use the 
        [pipeline schedule](https://docs.gitlab.com/ee/ci/pipelines/schedules.html) 
        function in conjunction with the rules option to run once a day as example.
        
        ```yaml
          rules:
            - if: '$CI_PIPELINE_SOURCE == "schedule"'
        ```
        
        ### Dockerfile Example
        
        Alternatively, you can optimize even further the job building a docker image for this job and uploading
        to [Gitlab Container Registry](https://docs.gitlab.com/ee/user/packages/container_registry).
        
        ```
        FROM python:3.9-alpine
        
        MAINTAINER foo@bar.com
        
        RUN pip install badges-gitlab
        ```
        
        ### Using the Badges
        
        This package seeks to use the post jobs availability of the artifacts 
        [through links](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html#access-the-latest-job-artifacts-by-url), 
        which are described in Gitlab  Documentation.
        
        #### Gitlab Project Badges
        
        You can insert using the project badges [https://docs.gitlab.com/ee/user/project/badges.html#badges]().
        
        Examples of a link for the project license in project badges section:
        
        ```
        https://gitlab.com/%{project_path}/-/jobs/artifacts/%{default_branch}/raw/public/badges/license_name.svg?job=badges
        ```
        
        ### Readme
        
        Other option is to use in the Readme file, through links. In Gitlab you can leverage the [relative links
        feature](https://docs.gitlab.com/ee/user/markdown.html#links).
        
        Example of a link in a markdown Readme.
        
        ```
        ![License](../-/jobs/artifacts/main/raw/public/badges/license_name.svg?job=badges)
        ```
         ## pyproject.toml Configuration
        
        It is now possible to configure this tool using pyproject.toml. 
        Currently the parameters path and junit-xml are supported.
        Example of pyproject.toml section:
        ```toml
        [tool.badges_gitlab]
        path = "public/badges"
        junit-xml = "tests/report.xml"
        ```
        Priority is:
        - Command line parameters
        - Toml configuration
        
        ## Author
        
        Felipe P. Silva
        
        ## Motivation
        
        Although it is possible to generate badges with other API's such as [shields.io](http://shields.io), 
        usually this process is not available in private repositories.
        
        So if you are hosting a public project, this package is not specifically meant 
        for you as you can workaround with other easier implementations.
        
        But, if you are hosting a private project and don't want to expose your project (Gitlab pages) 
        or don't want to risk exposing your credentials (API Requests), maybe this project is for you.
        
        Another reason would be to avoid overloading servers (e.g. shields.io) with unnecessary 
        requests for (re)creating badges.
        
        ## Design Choices
        
        Some design choices were made to create this package.
        1. The badges' generation were converted into two stages:
            - The first stage uses the Gitlab API (if the private-token turns out to be valid) to generate the json for some badges.
            - The second stage gets all the JSON files from the target folder and creates badges using anybadge.
        2. These two stages have a purpose, if any other CI Pipeline job generates json files with their own data, you can also use these files to create badges.
        3. The default directory is /public/badges:
            - This folder may be used later for Gitlab pages, although this can be modified through parameters.
        
        # Contributing
        Merge requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\
        Please make sure to update tests as appropriate.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
