gitlab-ci-tools's Introduction

Gitlab CI Tools

Scripts for getting useful information (e.g. the git hash of the last successful build) from within Gitlab CI

Overview

Often when using Gitlab CI you need information that is not available from the environment variables provided by the CI runner. This package contains a collection of scripts for obtaining information from the Gitlab API

License

gitlab-ci-tools is licensed under the simplfied (2-clause) BSD licence. See the LICENSE file for details.

Installation

The scripts are written in Python 3, so this will need to be installed prior to the following:

pip3 install gitlab-ci-tools

You can install the package on your local computer to test out the scripts (see the Usage section for details), however typically you will want to install this package into the Gitlab CI environment.

The simplest way to accomplish this is to add the following to the top of your .gitlab-ci.yml:

before_script:
    - pip3 install gitlab-ci-tools

Usage

Installing gitlab-ci-tools installs a bunch of scripts that you can run from the command line. See the next section for a list of the installed tools.

In order for the scripts to be able to access the Gitlab API you must provide a CI secret variable GITLAB_API_TOKEN that contains a personal access token with api scope (check out these instructions to find out how to generate one).

Security Considerations

Unfortunately Gitlab's API permissions are not very granular, so anyone with access to this token is, effectively, you (at least as far as Gitlab is concerned). If people you don't trust have access to your CI (e.g. they can make CI-triggering commits to your repository) this is a bad idea. There are several outstanding issues on Gitlab (e.g. #29566 and #41084) that attempt to address the problem of authenticated API access from within CI runners.

List of Tools

`last-good-build`

Print the Git hash of the last successful build for the current branch. An useful example would be generating a PDF of the diff between two Latex documents:

before_script:
  pip install gitlab-ci-tools
  LAST_GOOD_BUILD=$(last-good-build || echo '')

report diff:
  script:
    - git show $LAST_GOOD_BUILD:important_doc.tex > old_doc.tex
    - latexdiff old_doc.tex important_doc.tex > diff_doc.tex
    - latexmk -pdf diff_doc.tex
  artifacts:
    paths:
      - diff_doc.pdf

Contributing

I would be happy to add more tools here, not just ones that I find useful. It would be good if the script were to follow a similar structure to the existing ones (i.e. provide a main() function, and expose a command line that can be driven with command-line options or with environment variables), but I am happy to guide anyone through this process if need be.

Once there is more than a single script we can start to think about how best to separate out common functionlity so that we can reduce boilerplate.

gitlab-ci-tools's People

Contributors

Stargazers

Watchers

gitlab-ci-tools's Issues

Hello

Is this project still alive ?

Why have you moved it from gitlab to github ?

I have scripts that could be good inside your project.

They aim to get pypi packages last version (for local version only) and allow to increment it automatically. Not a big deal, but it doesn't belong in the package code.

Idea: create a specialized CI user

Gitlab CI does not allow to push via token, which may be useful for multiple purposes. The feature request is now open for 2 years, and still requires a design decision on the gitlab side AFAIK.

A possible workaround is to make access credentials available to CI. This can be done in multiple ways, but I think the easiest is to use http access via a token.

If a regular user wants to set up CI in this way, we're limited to store the user's API token in the repository variables. This comes with the risk of exposing all the user's access to gitlab.

On the other hand, an admin has a much better option: they may create a dedicated user, mark it as external (to limit the scope of what that user can do), mark the user's account as private, add the user to the repository as developer, and add the bot user impersonation token to the repository variables.

Then if the users wanted to give that bot access to another repository (e.g. a dependency), they may give the bot the corresponding permissions.

Further, this could be used in combination with gitlab's system hooks for repository creation and deletion to make creation of such bot users automatic.