Gira

Gira reacts to changes in your dependency files and bring you JIRA tickets mentioned in commits between current and updated version of the dependencies. Supported dependency files are

• pyproject.toml
• west.yaml/yml
• pubspec.yaml/yml

Gira is especially useful with pre-commit but is great for changelog enhancements when called as gira --format markdown -r <previousTag>

Pssst: works the best if your dependencies follow semantic release thus have tags in vX.Y.* format.

Usage - standalone

gira [-r revision] [-c config] [--format="commit|detail|markdown"]

Revision can be tag, branch, or a commit. By default gira check for staged/unstaged changes and if no are found then it diffs to the previous commit. This is the way to tell gira to diff to a different tag (for example).

Format can be short or detailed. Detailed formats will try to reach to your JIRA server for the details. The short (default) version is useful as suffix to commit messages. The markdown version is intended for changelogs.

$ gira [--format=commit]
internal-dependency1 <versionA> => <versionB>: JIRA-123, JIRA-567
other-followed-lib <versionA> => <versionB>: JIRA-876, JIRA-543

Config file is by default .gira.yaml but can be pretty much any YAML or pyproject.toml. See section bellow.

Usage - Pre-commit

$ pip install pre-commit
$ pre-commit install -t prepare-commit-msg -t pre-commit -t commit-msg

Add to your .pre-commit-config.yaml

  - repo: https://github.com/dronetag/gira
    rev: v1.0.1
    hooks:
    - id: gira
      # if you use other config than .gira.yaml then
      # args: ["-c", "your-config.yaml"]

Configuration

Gira is configured either by pyproject.toml or standalone .gira.yaml or actually any other YAML file that you specify with -c and has "gira.observe" and optionally "gira.jira" keys.

Observed Dependencies

Observed dependencies are in form of NAME=git-url where NAME must be the same as specified in your dependency/lock file.

[tool.gira.observe]
internal-lib1 = "github.com/company/internal-lib1"
other-dependency = "bitbucket.com/company/other-dependency"

or

gira:
  observe:
    internal-lib1: "github.com/company/internal-lib1"
    other-dependency: "bitbucket.com/company/other-dependency"

Submodules

Submodules are automatically added into observed dependencies. You can turn off support for submodules by settings gira.submodules=false in your config file.

JIRA (optional)

Example of a YAML configuration file section for JIRA (for pyproject.toml use tool.gira.jira). Token and email can be passed via environment variables JIRA_TOKEN or GIRA_JIRA_TOKEN and JIRA_EMAIL or GIRA_JIRA_EMAIL.

jira:
  url: jira.yourcompany.com
  token: token
  email: [email protected]

Setting JIRA connection information allows for "detailed" and "markdown" formatting of the output as follows:

$ gira
internal-dependency1 <versionA> => <versionB>:
  JIRA-123: details about the issue (url)
  JIRA-567: details about the issue (url)