jira-push-hook 0.1.0

Git pre-push hook that posts commit-message comments to Jira, with optional Gerrit support.

Jira Push Hook

This package provides a Jira automation CLI and an optional Git pre-push hook.

You can use it directly for Jira issue comments, worklogs, issue lookups, ticket search, and custom field updates. If you enable hook mode, it also runs a background worker during git push to post commit-message comments to Jira.

The hook worker is provider-agnostic for normal pushes and can optionally post a Gerrit review comment when pushing to refs/for/*.

Example commit subject:

P1732-82 :: feat(map_app): add unified property-based detected/raw columns across render APIs

Install From This Repo

From the repository root:

python3 -m pip install --user .
jira-push-hook scopes

or install in an isolated environment:

pipx install .
jira-push-hook scopes

CLI Commands

Available Jira automation commands:

jira-push-hook cloud-id
jira-push-hook check-auth
jira-push-hook scopes
jira-push-hook issue <ISSUE-KEY>
jira-push-hook list-issues <PROJECT> [--max N] [--jql ...]
jira-push-hook list-assignee --me|--account-id <ID>|--unassigned [--project PROJECT] [--max N]
jira-push-hook find-field [FIELD NAME]
jira-push-hook comment <ISSUE-KEY> [TEXT]
jira-push-hook worklog <ISSUE-KEY> <DURATION> [TEXT] [--started ...]
jira-push-hook ai-contribution <ISSUE-KEY> <VALUE>
jira-push-hook percent-done <ISSUE-KEY> <VALUE>

If you run jira-push-hook with no arguments, it starts the interactive Jira automation menu.

Git Hook Mode

Install the optional pre-push hook in a repository:

jira-push-hook install

That hook starts the packaged worker during pushes and writes logs under:

.git/push-comment-hook/logs/

Build A Wheel To Share

python3 -m pip install --upgrade build
python3 -m build

The wheel is written to:

dist/

Teammates can install that wheel with:

python3 -m pip install --user jira_push_hook-*.whl
jira-push-hook scopes

Jira Configuration

This package reads Jira settings from OS environment variables only. Export them in your current shell, terminal profile, or CI environment.

Set required variables in your current shell session:

export JIRA_EMAIL="your-email"
export JIRA_API_TOKEN="your-token"
export JIRA_SITE="your-site.atlassian.net"

To persist them for your user, add the same exports to your shell profile (~/.zshrc or ~/.bashrc) and open a new shell.

Supported values:

export JIRA_EMAIL="your-email"
export JIRA_API_TOKEN="your-token"
export JIRA_SITE="your-site.atlassian.net"

Optional values:

export JIRA_CLOUD_ID="your-cloud-id"
export JIRA_BASE_URL="https://your-site.atlassian.net"
export JIRA_API_VERSION="3"

Create A Jira API Token

Create a scoped Atlassian API token and use it as JIRA_API_TOKEN.

1. Open Atlassian account security and create an API token with scopes.
2. Select your Jira site.
3. Copy the token value and store it in your env file as JIRA_API_TOKEN.
4. Keep JIRA_EMAIL set to the Atlassian account email that owns the token.

If you want the token scopes to match the Jira helper this package was derived from, grant these Jira scopes:

Read
read:audit-log:jira
read:avatar:jira
read:comment:jira
read:comment.property:jira
read:field:jira
read:field-configuration:jira
read:group:jira
read:issue:jira
read:issue.changelog:jira
read:issue-details:jira
read:issue-meta:jira
read:issue-security-level:jira
read:issue-worklog:jira
read:issue-worklog.property:jira
read:issue.vote:jira
read:jira-user
read:project:jira
read:project-role:jira
read:status:jira
read:user:jira

Write
write:comment:jira
write:field:jira
write:issue:jira
write:issue-worklog:jira
write:issue-worklog.property:jira

For the current hook package, comment posting mainly depends on Jira comment access and issue access. The full scope set above is the safe choice if you want compatibility with the original Jira helper workflow as well.

JIRA_CLOUD_ID can be set directly to skip cloud ID discovery.

Hook Options

export PUSH_HOOK_POST_JIRA_COMMENT=1           # Enable Jira comments (default: 1).
export PUSH_HOOK_POST_GERRIT_COMMENT=0         # Enable Gerrit review comments (default: 0).
export POST_PUSH_COMMENT_INCLUDE_DETAILS=1      # Include commit/branch/change details.
export PUSH_HOOK_GERRIT_WAIT_SECONDS=120        # Max wait for Gerrit change visibility.
export PUSH_HOOK_GERRIT_POLL_SECONDS=5          # Poll interval for Gerrit lookup.

These settings affect hook mode and the background worker only.