Metadata-Version: 2.1
Name: gitlab-release
Version: 3.1
Summary: Utility for use in gitlab ci to upload files (from build) to the current projects release (tag)
Home-page: https://gitlab.com/alelec/gitlab-release
Author: Andrew Leech
Author-email: andrew@alelec.net
License: MIT
Platform: UNKNOWN
Requires-Dist: requests

gitlab-release
===============

This Python utility is used to upload specific release
files from a gitlab-ci build to the `Tags` release page on gitlab.

This allows a file or (generated) zip with arbitrary structure to be added to 
a release for convenient download, as opposed to the artifacts which are 
somewhat constrained to always be zipped with a folder structure taken 
directly from the filesystem.

It can be used in a ``.gitlab-ci.yml`` stage like:

::

    release:
      stage: release
      image: python3
      script:
        - pip3 install gitlab-release
        - gitlab-release *.zip
      only:
        - tags

Or if you want to bundle a bunch of files into a zip and upload that

::

    release:
      stage: release
      image: python3
      script:
        - pip3 install gitlab-release
        - gitlab-release --zip "release-${CI_COMMIT_TAG}.zip" *
      only:
        - tags

Or if you just want links to your job artifacts added to the release:

::

    release:
      stage: release
      image: python3
      script:
        - pip3 install gitlab-release
        - gitlab-release --link-artifact *.zip
      artifacts:
        paths:
          # Must include files passed to gitlab_release
          - ./*.zip
      only:
        - tags

On any tagged release the files specified on the command line will then be
available on the `Tags` tab of your project.

`gitlab-release` requires Python 3.


Setting up the required private token
---------------------------------------

This tool requires you to put a copy of a ``PRIVATE_TOKEN`` in a
secret CI variable for the project to give it access to post the files
back to the project.

For this create a new `Personal Access Token` at
https://gitlab.com/profile/personal_access_tokens and use that. (You
could also use your personal token from
https://gitlab.com/profile/account, but this is `not recommended`.)

Make sure you enable `Access your API` when creating the token. The
`name` of the token is just for you to remeber what it's for, it wont
affeect operation.

Add it to a secret variable called ``PRIVATE_TOKEN`` for the project you’re
building at ``https://gitlab.com/<user>/<project>/settings/ci_cd>``.


Usage
-----

::

    usage: gitlab-release [-h] [--server SERVER] [--project_id PROJECT_ID]
                         [--release_tag RELEASE_TAG] [--timeout TIMEOUT]
                         [--ignore_cert] [--job-id JOB_ID] [--artifact-zip]
                         [--zip ZIP] [--description DESCRIPTION]
                         [--link-artifact] [--private-token PRIVATE_TOKEN]
                         [files [files ...]]



========================= ===== 
positional arguments         
========================= =====
files                     file names and/or globs of files to upload
========================= ===== 


========================= ===== 
optional arguments           
========================= ===== 
--description DESCRIPTION Release description to be put in front of the files
--timeout TIMEOUT         Timeout for http requests
--ignore_cert             Ignore ssl certificate failures
--link-artifact           Link files as artifact from the current job instead of uploading
--artifact-zip            Link artifacts zip from current job
--job-id JOB_ID           Override the job number used for artifacts
--zip ZIP                 Add all provided files to provided zip name and upload that
--server SERVER           url of gitlab server (default: $CI_PROJECT_URL)
--project_id PROJECT_ID   Unique id of project, available in Project Settings/General (default: $CI_PROJECT_ID)
--release_tag RELEASE_TAG Tag to upload files against (default: $CI_BUILD_TAG)
--private_token           login token with permissions to commit to repo
-h, --help                show this help message and exit
========================= ===== 



