https://github.com/reload/bug-yield
Integrates Harvest and Jira timetracking
https://github.com/reload/bug-yield
Last synced: 17 days ago
JSON representation
Integrates Harvest and Jira timetracking
- Host: GitHub
- URL: https://github.com/reload/bug-yield
- Owner: reload
- Created: 2011-04-05T09:45:55.000Z (about 14 years ago)
- Default Branch: main
- Last Pushed: 2023-11-30T05:08:50.000Z (over 1 year ago)
- Last Synced: 2025-03-31T18:03:41.824Z (about 2 months ago)
- Language: PHP
- Homepage:
- Size: 622 KB
- Stars: 4
- Watchers: 15
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# BugYield
[](https://github.com/reload/bug-yield/actions?query=branch%3Amain)
[](https://codecov.io/gh/reload/bug-yield/branch/main)
BugYield is a console application which tracks changes to tickets
(issues, work items, bugs whatever) across systems (two-way) to avoid
tedious double registrations.
Which means that the developers only need to track time in Harvest,
and then ticket-titles will be transferred automatically from Jira to
the Harvest time entry AND time spend on that ticket will be
synchronized in Jira.
## Installation
Clone the repository and run composer install to install dependencies.
The PHP extensions curl, xml and mbstring are required.
## Configuration
BugYield needs to know where and how to access the systems involved.
This configuration is handled by a config.yml file. Copy the provided
config.sample.yml and update it with account information. If your
configuration file is not located in the root directory you can
specify the path to the config file using the `--config` option.
In order to send mails it needs a SendGrid key supplied in the
environment variable `SENDGRID_API_KEY`.
## Usage
BugYield currently supports two use cases:
1. *Time synchronization*: Mapping entries in Harvest to time elapsed in Jira tickets
2. *Title synchronization*: Mapping ticket titles from Jira to Harvest entries
BugYield works in the context of one or more Harvest projects
identified through their id, full name or code. Projects can be
specified in the configuration or using the
--harvest-project option. Use the magic name `all` to
specify all Harvest projects.
Run ./bugyield from the command line to show all available commands.
1. **Time synchronization** example:
`./bugyield tim --bugtracker=a-label` Run BugYield with the bugtracker defined in config.yml with the label `a-label`
2. **Title synchronization** example:
`./bugyield tit --bugtracker=a-label` Run BugYield with the bugtracker defined in config.yml with the label `a-label`
Just change the `--bugtracker=XXXX` with another label to run another
bugtracker. We have two Jira bugtrackers configured in the same
config.yml
### Running in docker
To build an image to run in docker, you must first build an image:
``` shell
docker build . -t reload/bug-yield:local
```
When running in docker, you should mount in the config file:
``` shell
docker run -v /path/to/config.yml:/bug-yield/config.yml reload/bug-yield:local
```
In development, you can mount in the full source and run a command
immediately:
``` shell
docker run -v $PWD:/bug-yield/ reload/bug-yield:local /bug-yield/bugyield --bugtracker=sometracker tim
```
### Time synchronization
BugYield can update tickets in Jira with time registrations in
Harvest. This makes it easier to show how much time has been spent on
a ticket and how this corresponds with estimates.
It works like this:
1. Add `#` (without the <>'s) in the Harvest entry
notes
2. Run the timesync command
3. The elapsed time field for the Jira ticket is updated and a new
worklog is added to the ticket showing the entry id, the time
spent, the task type and the notes from Harvest.
If the time or task for the Harvest entry is changed at a later point
in time, subsequent execution of the timesync command adds a new
comment to the ticket and the elapsed time field is adjusted
accordingly.
If a Harvest entry contains multiple ticket ids the time spent is
distributed evenly across the mentioned tickets.
If BugYield detects serious inconsistencies, then it will email the
offending user and optionally a separately defined email address (e.g.
to the Project Manager).
#### PRO TIP for JIRA
Make sure that the Closed state is editable in your Jira workflows,
thus enabling bugyield to update worklogs on closed issues - see [Jira
documentation](https://confluence.atlassian.com/display/JIRA/Allow+editing+of+Closed+Issues)
### Title synchronization
BugYield can update entries in Harvest with ticket titles from Jira.
This makes it easier register time on specific tickets without typing
other than the ticket-number (prefixed with a `#`). NOTE: When an
entry has been submitted and thereby locked, then we can't edit the
entry, and it will fail.
It works like this:
1. Add `` (without the <>'s) in the Harvest entry notes
2. Run the titlesync command
3. The entry notes in Harvest are updated with the ticket titles from
Jira replacing `` with `[]`
If a Jira ticket title is changed at a later point in time, subsequent
execution of the titlesync command makes sure that the Harvest entry
notes are updated accordingly.
## Known errors and problems
### Brackets in ticket titles
If you put brackets in your ticket title, you make it difficult for
BugYield to recognize our "codes". It will handle the ticket, but
display warnings and remove any comments on the Harvest entry created
by the user.