.. image:: https://github.com/con/tinuous/workflows/Test/badge.svg?branch=master :target: https://github.com/con/tinuous/actions?workflow=Test :alt: GitHub Actions Status

.. image:: https://travis-ci.com/con/tinuous.svg?branch=master :target: https://travis-ci.com/con/tinuous :alt: Travis CI Status

.. image:: https://ci.appveyor.com/api/projects/status/github/con/tinuous?branch=master&svg=true :target: https://ci.appveyor.com/project/yarikoptic/tinuous/branch/master :alt: Appveyor Status

.. image:: https://dl.circleci.com/status-badge/img/gh/con/tinuous/tree/master.svg?style=svg :target: https://dl.circleci.com/status-badge/redirect/gh/con/tinuous/tree/master :alt: CircleCI Status

.. image:: https://img.shields.io/pypi/pyversions/tinuous.svg :target: https://pypi.org/project/tinuous/

.. image:: https://img.shields.io/conda/vn/conda-forge/tinuous.svg :target: https://anaconda.org/conda-forge/tinuous :alt: Conda Version

.. image:: https://img.shields.io/github/license/con/tinuous.svg :target: https://opensource.org/licenses/MIT :alt: MIT License

GitHub <https://github.com/con/tinuous>_ | PyPI <https://pypi.org/project/tinuous/>_ | Anaconda <https://anaconda.org/conda-forge/tinuous>_ | Issues <https://github.com/con/tinuous/issues>_ | Changelog <https://github.com/con/tinuous/blob/master/CHANGELOG.md>_

tinuous is a command for downloading build logs, artifacts, & release assets for a GitHub repository from GitHub Actions, Travis-CI.com, Appveyor, and/or CircleCI.

See https://github.com/con/tinuous-inception for an example setup that uses tinuous with GitHub Actions to fetch the CI logs for tinuous itself.

Installation

tinuous requires Python 3.9 or higher. Just use pip <https://pip.pypa.io>_ for Python 3 (You have pip, right?) to install tinuous and its dependencies::

python3 -m pip install tinuous

tinuous can also optionally integrate with DataLad_. To install DataLad alongside tinuous, specify the datalad extra::

python3 -m pip install "tinuous[datalad]"

tinuous is also available for conda! To install, run::

conda install -c conda-forge tinuous

Usage

::

tinuous [<global options>] <command> [<args> ...]

Global Options

-c FILE, --config FILE Read configuration from the given file [default value: tinuous.yaml]

-E FILE, --env FILE Load environment variables from the given .env file. By default, environment variables are loaded from the first file named ".env" found by searching from the current directory upwards.

                            **Warning**: Care must be taken when this file
                            is located in a Git repository so as not to
                            publicly expose it: either list the file in
                            ``.gitignore`` or, if using DataLad or
                            git-annex, configure git-annex to prohibit
                            public sharing of the file.

-l LEVEL, --log-level LEVEL Set the log level to the given value. Possible values are "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG" (all case-insensitive) and their Python integer equivalents. [default value: INFO]

fetch Command

::

tinuous [<global options>] fetch [<options>]

tinuous fetch reads a configuration file telling it what repository to retrieve logs & artifacts for, where to retrieve them from, and where to save them, and then it carries those steps out.

Options

--sanitize-secrets              Sanitize secrets from log files after
                                downloading

-S FILE, --state FILE           Store program state (e.g., timestamps before
                                which all asset are known to have been fetched)
                                in the given file [default value:
                                ``.tinuous.state.json``]

--since TIMESTAMP               Override the ``since`` timestamp to force
                                refetching builds after the given time.  This
                                overrides both the state file and configuration
                                file settings.  Accepts ISO 8601 timestamps
                                (e.g., ``2025-01-02T00:00:00Z``) or relative
                                times (e.g., ``3 days ago``, ``1 week ago``).
                                Useful for refetching recent runs that may have
                                been rerun or updated.

``fetch-commit`` Command
------------------------

::

    tinuous [<global options>] fetch-commit [<options>] <committish>

Download logs and build artifacts for just the given committish.   The
statefile is not updated.

This command only supports retrieving resources from GitHub.

Options

--sanitize-secrets Sanitize secrets from log files after downloading

sanitize Command

::

tinuous [<global options>] sanitize <path> ...

Sanitize the given files, replacing all strings matching a secret regex with a series of asterisks.

Configuration

The configuration file is a YAML file containing a mapping with the following keys:

repo (required) The GitHub repository to retrieve assets for, in the form OWNER/NAME

vars A mapping defining custom path template placeholders. Each key is the name of a custom placeholder, without enclosing braces, and the value is the string to substitute in its place. Custom values may contain standard path template placeholders as well as other custom placeholders.

ci (required) A mapping from the names of the CI systems from which to retrieve assets to sub-mappings containing CI-specific configuration. Including a given CI system is optional; assets will only be fetched from a given system if it is listed in this mapping.

The CI systems and their sub-mappings are as follows:

``github``
    Configuration for retrieving assets from GitHub Actions.  Subfields:

    ``paths``
        A mapping giving `template strings <Path Templates_>`_ for the
        paths at which to save various types of assets.  If this is empty
        or not present, no assets are retrieved.  Subfields:

        ``logs``
            A template string that will be instantiated for each workflow
            run to produce the path for the directory (relative to the
            current working directory) under which the run's build logs
            will be saved.  If this is not specified, no logs will be
            downloaded.

        ``artifacts``
            A template string that will be instantiated for each workflow
            run to produce the path for the directory (relative to the
            current working directory) under which the run's artifacts will
            be saved.  If this is not specified, no artifacts will be
            downloaded.

        ``releases``
            A template string that will be instantiated for each
            (non-draft, non-prerelease) GitHub release to produce the path
            for the directory (relative to the current working directory)
            under which the release's assets will be saved.  If this is not
            specified, no release assets will be downloaded.

    ``workflows``
        A specification of the workflows for which to retrieve assets.
        This can be either a list of workflow basenames, including the file
        extension (e.g., ``test.yml``, not ``.github/workflows/test.yml``)
        or a mapping containing the following fields:

        ``include``
            A list of workflows to retrieve assets for, given as either
            basenames or (when ``regex`` is true) `Python regular
            expressions`_ to match against basenames.  If ``include`` is
            omitted, it defaults to including all workflows.

        ``exclude``
            A list of workflows to not retrieve assets for, given as either
            basenames or (when ``regex`` is true) `Python regular
            expressions`_ to match against basenames.  If ``exclude`` is
            omitted, no workflows are excluded.  Workflows that match both
            ``include`` and ``exclude`` are excluded.

        ``regex``
            A boolean.  If true (default false), the elements of the
            ``include`` and ``exclude`` fields are treated as `Python
            regular expressions`_ that are matched (unanchored) against
            workflow basenames; if false, they are used as exact names

        When ``workflows`` is not specified, assets are retrieved for all
        workflows in the repository.

``travis``
    Configuration for retrieving logs from Travis-CI.com.  Subfield:

    ``paths``
        A mapping giving `template strings <Path Templates_>`_ for the
        paths at which to save various types of assets.  If this is empty
        or not present, no assets are retrieved.  Subfield:

        ``logs``
            A template string that will be instantiated for each job of
            each build to produce the path for the file (relative to the
            current working directory) in which the job's logs will be
            saved.  If this is not specified, no logs will be downloaded.

``appveyor``