> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# tracktor/ci-tools

Orb with python and docker building / publish utilities. Utilities included:
  - Python:
    - Run test
    - Export poetry configuration and version
    - Load poetry version as env variable
  - Docker:
    - Build image (with buildx)
    - Publish image to docker hub
  - Javascript/Typescript:
    - Load version from package.json


## Commands

### build-docker

Build a docker image by pulling first the latest image version to be used for a faster build with caching.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_params` | string |  |  |
| `builder` | string | circleci-builder |  |
| `cache_tag` | string | cache |  |
| `dockerfile` | string | Dockerfile |  |
| `image_name` | string |  |  |
| `latest_tag` | string | latest |  |
| `publish` | boolean | false |  |
| `registry_pwd` | string |  |  |
| `registry_user` | string |  |  |
| `tag` | string | 0.0.0 |  |

### bump-version

Bump the version of the project based on commit messages. Updates the CHANGELOG.md file.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch` | string |  | Branch to use to bump the version (default current) |
| `build` | boolean | true | Build the project after bumping the version (python only) |
| `ci_email` | env_var_name | CI_EMAIL | Email to use for the git commit |
| `ci_user` | env_var_name | CI_USER | User to use for the git commit |
| `custom-args` | string |  | Custom arguments to pass to the bump version command |
| `dry-run` | boolean | false | Do not commit or push the changes |
| `lang` | string |  | Language of the project: js or python |
| `sign` | boolean | false | Sign the commit |
| `tool` | string | poetry | Tool to use for bumping the version |

### export-poetry

Export the requirements and the version number from a pyproject.toml file


| Parameter | Type | Default | Description |
|---|---|---|---|
| `extras` | string |  | Extra parameters to pass to export (for instance '--without-hashes') |

### export-requirements

Export the requirements and the version number from a pyproject.toml file


| Parameter | Type | Default | Description |
|---|---|---|---|
| `extras` | string |  | Extra parameters to pass to export (for instance '--without-hashes') |
| `persist_to_workspace` | boolean | true | Persist the requirements.txt and .version files to the workspace |
| `tool` | string | poetry | The tool to use for exporting requirements |

### load-docker-tag

Load the LATEST_DOCKER_TAG into an environment variable depending on the branch


| Parameter | Type | Default | Description |
|---|---|---|---|
| `fail_no_tag` | boolean | true | Fail if the tag is not found |

### load-package-version

Load the version into an environment variable using the value from package.json


### load-version

Load the version into an environment variable


### run-python-tests

Using a pyproject.toml file, runs formatting, pyright then pytest with coverage


| Parameter | Type | Default | Description |
|---|---|---|---|
| `before-steps` | steps |  | Steps that will be executed before dependencies are installed |
| `cache-version` | string | v0 | Cache version (needed in case of cache issue) |
| `extras` | string |  | Package install extra parameters (only for poetry) |
| `formatter` | enum | ruff | Library used to check format |
| `skip-format` | boolean | false | Skip formatting |
| `skip-lint` | boolean | false | Skip linting |
| `skip-typecheck` | boolean | false | Skip checking types |
| `tests-extras` | string |  | Extra parameters for running tests |
| `tool` | string | poetry | The tool to use for running tests |

### track-bump

Bump version and tags of the project


| Parameter | Type | Default | Description |
|---|---|---|---|
| `after-steps` | steps |  | Steps to run before pushing the changes |
| `branch` | string |  | Branch to use to bump the version (default current) |
| `changelog-params` | string | -o CHANGELOG.md | Arguments to pass to the changelog generation |
| `ci_email` | env_var_name | CI_EMAIL | Email to use for the git commit |
| `ci_user` | env_var_name | CI_USER | User to use for the git commit |
| `default-branch` | string | main | Default branch |
| `dry-run` | boolean | false | Do not commit or push the changes |
| `params` | string |  | Arguments to pass to the bump |
| `sign` | boolean | false | Sign the commit |
| `skip-changelog` | boolean | false | Skip generating the changelog |
| `tag-pattern` | string |  | Pattern to pass to git-cliff |
| `track-bump-version` | string | latest | Version of the track-bump library |
| `verbose` | boolean | false | Print the commands executed |

## Executors

### default

This is a sample executor using Docker and Node. If you want to provide a custom environment in your orb, insert your image here. If you do not require an executor, you can simply delete this directory.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | lts | Pick a specific cimg/node image variant: https://hub.docker.com/r/cimg/node/tags
 |

## Examples

### example

Sample example description.


```yaml
version: '2.1'
orbs:
  <orb-name>: <namespace>/<orb-name>@1.2.3
workflows:
  use-my-orb:
    jobs:
      - <orb-name>/<job-name>
```