gitlab-artifact-download

Overview

gitlab-artifact-download is a small tool for downloading an artifact created by a gitlab CI job.

The following actions can be run automatically after downloading the artifact:

• deb_install: install the specified deb package files
• please suggest further useful actions

The download occurs in a temporary directory by default. A custom permanent location can also be specified.

Installation

Pick one of the following approaches:

• download the script: wget https://notabug.org/sumpfralle/gitlab-artifact-download/raw/main/gitlab-artifact-download
• install a deb package

Requirements

• jq
• unzip

Usage

gitlab-artifact-download supports configuration either via a configuration file or via environment variables.

Run without configuration file

One-time operations may be executed by providing the relevant details via environment variables:

GITLAB_BASE_URL=https://gitlab.com \
    GITLAB_PROJECT=example/foo \
    GITLAB_AUTH_TOKEN=YOUR_PRIVATE_AUTH_TOKEN \
    GITLAB_JOB_NAME=deb_package \
    ACTIONS=deb_install \
    DEB_PACKAGE_NAMES="foo foo-dependencies" \
    gitlab-artifact-download install

Run with a configuration file

The following example configuration specifies a download operation followed by the installation of deb packages via dpkg:

{
    "base_url": "https://gitlab.com",
    "project": "example/foo",
    "job_name": "deb_package",
    "auth_token": "YOUR_PRIVATE_AUTH_TOKEN",
    "actions": [
        "deb_install"
    ],
    "deb": {
        "package_directory": "build/debian",
        "package_names": [
            "foo",
            "foo-dependencies"
        ]
    }
}

This configuration file can be located in current directory or in the user's home directory as .gitlab-artifact-download.json.

With the example configuration file above, the following call is sufficient:

gitlab-artifact-download install

Runtime arguments

The following commands are supported:

• install [REFERENCE]: download and process the latest artifact for the given reference (commit ID, branch, tag or job ID; REFERENCE defaults to main)
• list: list the most recently built artifacts (including their expire date)
• list-json: list the most recently built artifacts (including their expire date, JSON format)
• help: a short overview

Configuration

Most configuration settings (except for the location of the configuration file) can be specified either via an environment variable or in a JSON-formatted configuration file.

The following precedence applies (the first match wins):

1. environment variable
2. setting in first configuration file
3. setting in second configuration file
4. ...

Environment variable	JSON path	Type	Required?	Description
CONFIG_FILE	-	string	no	Location of the configuration file to be loaded. If this environment variable is undefined, then all files specified in DEFAULT_CONFIG_FILES are parsed (if they exist).
DEFAULT_CONFIG_FILES	-	space-separated filenames	no	Defaults to .gitlab-artifact-download.json ~/.gitlab-artifact-download.json (first: current directory, then user's home directory).
GITLAB_BASE_URL	.base_url	string	yes	The base URL of the gitlab instance (e.g. https://gitlab.com).
GITLAB_PROJECT	.project	string or integer	yes	The name of the project (including its groups) or the project ID.
GITLAB_JOB_NAME	.job_name	string	yes	The name of the gitlab CI job, which generates the artifacts.
GITLAB_AUTH_TOKEN	.auth_token	string	yes	A gitlab access token (personal or project-related) with full api permissions (read_api is currently not sufficient, see gitlab#296476).
DOWNLOAD_DIRECTORY	.download_directory	string	no	The content of the artifact archive is extracted to this directory, if it is specified. By default (if unset), the archive is extracted to a temporary directory, which is removed after processing.
ACTIONS	.actions	array of strings	no	Certain actions can be executed after the downloading and extracting the artifact archive. See the list of supported actions below.

Actions

Some actions accept additional configuration settings. These are documented as the environment variable name and the JSON path (see above).

Deb package installation (deb_install)

• DEB_PACKAGE_DIRECTORY / .deb.package_directory: (optional) directory within the archive, which contains *.deb files
• DEB_PACKAGE_NAMES / .deb.package_names: list of package names to be installed

License

gitlab-artifact-download is published under the GPLv3 or later.