This gem allows you to easily use the Pivotal Tracker v5 API.
Itβs powered by Faraday and Virtus.
This gem is tested against the following officially supported Ruby versions:
- Minimum Ruby Version: 2.7.x
- Latest Ruby Supported: 3.2.x
Add this line to your application's Gemfile:
gem 'tracker_api'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install tracker_api
client = TrackerApi::Client.new(token: 'my-api-token') # Create API client
client.me.email # Get email for the authenticated person
client.activity # Get a list of all the activity performed the authenticated person
client.notifications # Get notifications for the authenticated person
projects = client.projects # Get all projects
project = client.project(123456) # Find project with given ID
project.activity # Get a list of all the activity performed on this project
project.stories # Get all stories for a project
project.stories(with_state: :unscheduled, limit: 10) # Get 10 unscheduled stories for a project
project.stories(filter: 'requester:OWK label:"jedi stuff"') # Get all stories that match the given filters
project.create_story(name: 'Destroy death star') # Create a story with the name 'Destroy death star'
project.search('Destroy death star') # Get a search result with all epics and stories relevant to the query
story = project.story(847762630) # Find a story with the given ID
story.activity # Get a list of all the activity performed on this story
story.transitions # Get a list of all the story transitions on this story
story.name = 'Save the Ewoks' # Update a single story attribute
story.attributes = { name: 'Save the Ewoks', description: '...' } # Update multiple story attributes
story.add_label('Endor') # Add a new label to an existing story
story.save # Save changes made to a story
story = client.story(117596687) # Get a story with story ID only
story = TrackerApi::Resources::Story.new( client: client,
project_id: 123456,
id: 847762630) # Use the Story resource to get the story
comments = story.comments # comments without first fetching the story
comment = story.create_comment(text: "Use the force!") # Create a new comment on the story
comment = story.create_comment(text: "Use the force again !", # Create a new comment on the story with
files: ['path/to/an/existing/file']) # file attachments
comment.text += " (please be careful)"
comment.save # Update text of an existing comment
comment.delete # Delete an existing comment
comment.create_attachments(files: ['path/to/an/existing/file']) # Add attachments to existing comment
comment.delete_attachments # Delete all attachments from a comment
attachments = comment.attachments # Get attachments associated with a comment
attachments.first.delete # Delete a specific attachment
comment.attachments(reload: true) # Re-load the attachments after modification
task = story.tasks.first # Get story tasks
task.complete = true
task.save # Mark a task complete
review = story.reviews.first # Mark a review as complete
review.status = 'pass'
review.save
epics = project.epics # Get all epics for a project
epic = epics.first
label = epic.label # Get an epic's label
workspaces = client.workspaces # Get person's multi-project workspaces
See Pivotal Tracker API documentation for how to use the fields
parameter.
client = TrackerApi::Client.new(token: 'my-api-token') # Create API client
client.project(project_id, fields: ':default,labels(name)') # Eagerly get labels with a project
client.project(project_id, fields: ':default,epics') # Eagerly get epics with a project
client.project(project_id).stories(fields: ':default,tasks') # Eagerly get stories with tasks
story.comments(fields: ':default,person') # Eagerly get comments and the person that made the comment for a story
TrackerApi::Errors::ClientError
is raised for 4xx HTTP status codes
TrackerApi::Errors::ServerError
is raised for 5xx HTTP status codes
Direct mutation of an attribute value skips coercion and dirty tracking. Please use direct assignment or the specialized add_* methods to get expected behavior. https://github.com/solnic/virtus#important-note-about-member-coercions
This will cause coercion and dirty tracking to be bypassed and the new label will not be saved.
story = project.story(847762630)
label = TrackerApi::Resources::Label.new(name: 'Special Snowflake')
# BAD
story.labels << label
story.save
# GOOD
story.labels = story.labels.dup.push(label)
story.save
- Add missing resources and endpoints
- Add create, update, delete for resources
- Error handling for error responses
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Currently this client supports read-only access to Pivotal Tracker. We will be extending it as our use cases require, but are always happy to accept contributions.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request