GitHub API Plugin for Fastlane

Overview
Installation
Available Actions
Return Values
Authentication
Example Usage
Development
Troubleshooting

Getting Started

This project is a fastlane plugin. To get started with fastlane-plugin-github_api, add it to your project by running:

fastlane add_plugin github_api

Requirements

Ruby 2.5.0 or higher
Fastlane 2.170.0 or higher

About github_api

A comprehensive Fastlane plugin for interacting with GitHub's REST APIs. This plugin enables automation of GitHub-related tasks directly from your Fastlane workflows, including managing issues, pull requests, repositories, labels, milestones, and more.

Key Features

Full coverage of GitHub REST API endpoints for common operations
Consistent Ruby-style interface for all GitHub interactions
Detailed error handling and response parsing
Shared lane context values for chaining multiple actions
Comprehensive documentation and examples

Available Actions

Issues

github_add_assignees: Add assignees to an issue.
github_add_labels: Add labels to an issue.
github_create_issue: Create a new issue.
github_create_issue_comment_reaction: Create a reaction for an issue comment.
github_create_issue_reaction: Create a reaction for an issue.
github_delete_issue_comment: Delete an issue comment.
github_delete_issue_comment_reaction: Delete a reaction from an issue comment.
github_delete_issue_reaction: Delete a reaction from an issue.
github_get_issue: Get a single issue.
github_get_issue_comment: Get a single issue comment.
github_get_issue_event: Get a single issue event.
github_get_issue_timeline: List events for an issue timeline.
github_list_issue_comment_reactions: List reactions for an issue comment.
github_list_issue_comments: List comments on an issue.
github_list_issue_labels: List labels on an issue.
github_list_issue_reactions: List reactions for an issue.
github_list_issues: List issues in a repository.
github_lock_issue: Lock an issue.
github_remove_all_labels: Remove all labels from an issue.
github_remove_assignees: Remove assignees from an issue.
github_remove_label: Remove a label from an issue.
github_set_labels: Set labels for an issue.
github_unlock_issue: Unlock an issue.
github_update_issue: Update an issue.
github_update_issue_comment: Update an issue comment.

Pull Requests

github_check_pull_merged: Check if a pull request has been merged.
github_create_pull: Create a pull request.
github_create_pull_comment: Create a review comment for a pull request.
github_create_pull_comment_reaction: Create a reaction for a pull request review comment.
github_create_pull_review: Create a review for a pull request.
github_delete_pull_comment: Delete a pull request review comment.
github_delete_pull_comment_reaction: Delete a reaction from a pull request review comment.
github_dismiss_pull_review: Dismiss a pull request review.
github_get_pull: Get a single pull request.
github_get_pull_comment: Get a single pull request review comment.
github_get_pull_review: Get a single pull request review.
github_get_pull_review_comments: List comments for a pull request review.
github_list_all_pull_comments: List all pull request review comments in a repository.
github_list_pull_comment_reactions: List reactions for a pull request review comment.
github_list_pull_comments: List review comments on a pull request.
github_list_pull_commits: List commits on a pull request.
github_list_pull_files: List files on a pull request.
github_list_pull_reviewers: List requested reviewers for a pull request.
github_list_pull_reviews: List reviews on a pull request.
github_list_pulls: List pull requests in a repository.
github_merge_pull: Merge a pull request.
github_request_pull_review: Request reviewers for a pull request.
github_remove_pull_reviewers: Remove requested reviewers from a pull request.
github_submit_pull_review: Submit a review for a pull request.
github_update_pull: Update a pull request.
github_update_pull_branch: Update a pull request branch.
github_update_pull_comment: Update a pull request review comment.
github_update_pull_review: Update a pull request review.

Repositories

github_create_repository: Create a new repository.
github_delete_repository: Delete a repository.
github_list_repo_labels: List labels for a repository.
github_list_repo_issue_events: List issue events for a repository.
github_list_milestones: List milestones for a repository.
github_create_label: Create a label.
github_update_label: Update a label.
github_delete_label: Delete a label.
github_create_milestone: Create a milestone.
github_update_milestone: Update a milestone.
github_delete_milestone: Delete a milestone.

Reactions

github_create_commit_comment_reaction: Create a reaction for a commit comment.
github_delete_commit_comment_reaction: Delete a reaction from a commit comment.
github_list_commit_comment_reactions: List reactions for a commit comment.

Return Values

All actions return a hash with the following keys:

:status - The HTTP status code
:body - The raw response body
:json - Parsed JSON response (if applicable)

Most actions also set shared lane context values that can be accessed in subsequent steps:

result = github_create_issue(...)
puts "Issue number: #{Actions.lane_context[SharedValues::GITHUB_CREATE_ISSUE_JSON]['number']}"

Authentication

All actions require GitHub authentication via a Personal Access Token:

ENV["GITHUB_API_TOKEN"] = "your-token-here" # Set in your environment

# Or pass directly to actions
github_create_issue(
  api_token: "your-token-token",
  # other parameters...
)

You can create a GitHub Personal Access Token at https://github.com/settings/tokens.

Token Permissions

For most operations, your token will need the following scopes:

repo - Full control of private repositories
admin:org - For organization-related operations
user - For user-related operations

For specific operations, refer to GitHub's documentation on token scopes.

Example

Check out the example Fastfile to see how to use this plugin. Try it by cloning the repo, running fastlane install_plugins and bundle exec fastlane test.

Sample Usage

# In your Fastfile
lane :create_release_issue do
  github_create_issue(
    repo_owner: "your-username",
    repo_name: "your-repo",
    title: "Release version #{lane_context[SharedValues::VERSION_NUMBER]}",
    body: "Please review the following changes for this release...",
    labels: ["release", "needs-review"]
  )
end

lane :submit_pr_review do
  github_submit_pull_review(
    repo_owner: "your-username",
    repo_name: "your-repo",
    pull_number: 42,
    event: "APPROVE",
    body: "LGTM! :rocket:"
  )
end

Run tests for this plugin

To run both the tests, and code style validation, run:

rake

To automatically fix many of the styling issues, use:

rubocop -a

Issues and Feedback

For any other issues and feedback about this plugin, please submit it to this repository.

Troubleshooting

If you have trouble using plugins, check out the Plugins Troubleshooting guide.

Common Issues

Authentication Problems

Make sure your GitHub token has the correct permissions
Check that your token is valid and not expired
Verify the token is correctly set as an environment variable or passed to the action

Rate Limiting

GitHub API has rate limits that might affect high-frequency usage
Consider implementing retry logic or rate limit handling

Using fastlane Plugins

For more information about how the fastlane plugin system works, check out the Plugins documentation.

About fastlane

fastlane is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out fastlane.tools.

Complete Action Reference Guide

This comprehensive reference guide provides detailed usage examples, required parameters, and expected outputs for all actions available in the GitHub API plugin. Use these examples as templates for your own Fastlane workflows.

Issues

`github_add_assignees`

Add one or more assignees to a GitHub issue.

github_add_assignees(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  assignees: ["octocat", "hubot"]
)

`github_add_labels`

Add one or more labels to a GitHub issue.

github_add_labels(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  labels: ["bug", "help wanted"]
)

`github_create_issue`

Create a new GitHub issue.

github_create_issue(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  title: "Found a bug",
  body: "This is a description of the bug.",
  labels: ["bug"],
  assignees: ["octocat"],
  milestone: 1
)

`github_get_issue`

Get a single GitHub issue.

issue = github_get_issue(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42
)

puts "Issue title: #{issue[:json]['title']}"
puts "Issue state: #{issue[:json]['state']}"

`github_update_issue`

Update an existing issue.

github_update_issue(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  title: "Updated issue title",
  body: "Updated description",
  state: "closed", # "open" or "closed"
  labels: ["bug", "wontfix"],
  assignees: ["octocat"],
  milestone: 2
)

`github_list_issues`

List issues in a repository.

issues = github_list_issues(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  state: "open", # "open", "closed", or "all"
  sort: "created", # "created", "updated", "comments"
  direction: "desc", # "asc" or "desc"
  since: "2023-01-01T00:00:00Z", # Optional
  labels: "bug,enhancement", # Optional
  assignee: "octocat", # Optional
  creator: "octocat", # Optional
  mentioned: "octocat", # Optional
  milestone: 1 # Optional
)

issues[:json].each do |issue|
  puts "##{issue['number']} - #{issue['title']} (#{issue['state']})"
end

`github_add_issue_comment`

Add a comment to a GitHub issue.

github_add_issue_comment(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  body: "This is a comment on the issue."
)

`github_list_issue_comments`

List comments on an issue.

comments = github_list_issue_comments(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  since: "2023-01-01T00:00:00Z" # Optional
)

comments[:json].each do |comment|
  puts "Comment by #{comment['user']['login']}: #{comment['body']}"
end

Pull Requests

`github_create_pull`

Create a new pull request.

pull = github_create_pull(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  title: "Amazing new feature",
  body: "Please pull these awesome changes in!",
  head: "octocat:feature-branch",
  base: "main",
  draft: false,
  maintainer_can_modify: true
)

puts "Created PR ##{pull[:json]['number']}"

`github_get_pull`

Get a single pull request.

pull = github_get_pull(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  pull_number: 42
)

puts "PR Title: #{pull[:json]['title']}"
puts "Branch: #{pull[:json]['head']['ref']} -> #{pull[:json]['base']['ref']}"
puts "State: #{pull[:json]['state']}"

`github_update_pull`

Update a pull request.

github_update_pull(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  pull_number: 42,
  title: "Updated pull request title",
  body: "Updated description",
  state: "closed", # "open" or "closed"
  base: "main", # Branch to merge changes into
  maintainer_can_modify: true
)

`github_list_pulls`

List pull requests in a repository.

pulls = github_list_pulls(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  state: "open", # "open", "closed", "all"
  head: "octocat:feature", # Optional filter by head branch
  base: "main", # Optional filter by base branch
  sort: "created", # "created", "updated", "popularity", "long-running"
  direction: "desc" # "asc" or "desc"
)

pulls[:json].each do |pull|
  puts "PR ##{pull['number']}: #{pull['title']}"
end

`github_merge_pull`

Merge a pull request.

github_merge_pull(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  pull_number: 42,
  commit_title: "Merge pull request #42", # Optional
  commit_message: "Merge pull request #42 from octocat/feature", # Optional
  merge_method: "merge" # "merge", "squash", or "rebase"
)

`github_check_pull_merged`

Check if a pull request has been merged.

result = github_check_pull_merged(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  pull_number: 42
)

if result[:status] == 204
  UI.success "Pull request has been merged!"
else
  UI.message "Pull request has not been merged."
end

`github_list_pull_commits`

List commits on a pull request.

commits = github_list_pull_commits(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  pull_number: 42
)

commits[:json].each do |commit|
  puts "Commit SHA: #{commit['sha']}"
  puts "Author: #{commit['commit']['author']['name']}"
  puts "Message: #{commit['commit']['message']}"
end

`github_list_pull_files`

List files on a pull request.

files = github_list_pull_files(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  pull_number: 42
)

files[:json].each do |file|
  puts "File: #{file['filename']}"
  puts "Status: #{file['status']}"
  puts "Additions: #{file['additions']}, Deletions: #{file['deletions']}, Changes: #{file['changes']}"
end

Repositories

`github_create_repository`

Create a new repository.

github_create_repository(
  api_token: "<your_github_token>",
  name: "new-repo",
  description: "This is a new repository",
  private: false,
  has_issues: true,
  has_projects: true,
  has_wiki: true,
  auto_init: true,
  gitignore_template: "Ruby",
  license_template: "mit",
  organization: "octo-org" # Optional, create in organization instead of user account
)

`github_delete_repository`

Delete a repository.

github_delete_repository(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World"
)

`github_list_repo_labels`

List labels for a repository.

labels = github_list_repo_labels(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World"
)

labels[:json].each do |label|
  puts "Label: #{label['name']} (#{label['color']})"
end

`github_create_label`

Create a label in a repository.

github_create_label(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  name: "bug",
  color: "f29513",
  description: "Something isn't working" # Optional
)

`github_update_label`

Update a label in a repository.

github_update_label(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  name: "bug",
  new_name: "confirmed-bug", # Optional, only if changing the name
  color: "b60205",
  description: "Confirmed bugs that need to be fixed"
)

`github_delete_label`

Delete a label from a repository.

github_delete_label(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  name: "wontfix"
)

`github_list_milestones`

List milestones for a repository.

milestones = github_list_milestones(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  state: "open", # "open", "closed", "all"
  sort: "due_on", # "due_on" or "completeness"
  direction: "asc" # "asc" or "desc"
)

milestones[:json].each do |milestone|
  puts "Milestone: #{milestone['title']} (#{milestone['state']})"
  puts "Due on: #{milestone['due_on']}"
end

`github_create_milestone`

Create a milestone in a repository.

github_create_milestone(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  title: "v1.0",
  state: "open", # "open" or "closed"
  description: "Tracking milestone for version 1.0",
  due_on: "2023-12-31T23:59:59Z" # Optional due date
)

`github_update_milestone`

Update a milestone in a repository.

github_update_milestone(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  milestone_number: 1,
  title: "Updated title", # Optional
  state: "closed", # Optional, "open" or "closed"
  description: "Updated description", # Optional
  due_on: "2024-01-31T23:59:59Z" # Optional due date
)

`github_delete_milestone`

Delete a milestone from a repository.

github_delete_milestone(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  milestone_number: 1
)

Reactions

`github_create_issue_reaction`

Create a reaction for an issue.

github_create_issue_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  content: "+1" # Available reactions: +1, -1, laugh, confused, heart, hooray, rocket, eyes
)

`github_list_issue_reactions`

List reactions for an issue.

reactions = github_list_issue_reactions(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  content: "+1" # Optional filter by reaction type
)

puts "Total reactions: #{reactions[:json].count}"

`github_delete_issue_reaction`

Delete a reaction from an issue.

github_delete_issue_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  issue_number: 42,
  reaction_id: 12345
)

`github_create_issue_comment_reaction`

Create a reaction for an issue comment.

github_create_issue_comment_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  content: "heart" # Available reactions: +1, -1, laugh, confused, heart, hooray, rocket, eyes
)

`github_list_issue_comment_reactions`

List reactions for an issue comment.

reactions = github_list_issue_comment_reactions(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  content: "heart" # Optional filter by reaction type
)

puts "Total reactions: #{reactions[:json].count}"

`github_delete_issue_comment_reaction`

Delete a reaction from an issue comment.

github_delete_issue_comment_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  reaction_id: 12345
)

`github_create_pull_comment_reaction`

Create a reaction for a pull request review comment.

github_create_pull_comment_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  content: "heart" # Available reactions: +1, -1, laugh, confused, heart, hooray, rocket, eyes
)

`github_list_pull_comment_reactions`

List reactions for a pull request review comment.

reactions = github_list_pull_comment_reactions(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  content: "heart" # Optional filter by reaction type
)

puts "Total reactions: #{reactions[:json].count}"

`github_delete_pull_comment_reaction`

Delete a reaction from a pull request review comment.

github_delete_pull_comment_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  reaction_id: 12345
)

`github_create_commit_comment_reaction`

Create a reaction for a commit comment.

github_create_commit_comment_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  content: "heart" # Available reactions: +1, -1, laugh, confused, heart, hooray, rocket, eyes
)

`github_list_commit_comment_reactions`

List reactions for a commit comment.

reactions = github_list_commit_comment_reactions(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  content: "heart" # Optional filter by reaction type
)

puts "Total reactions: #{reactions[:json].count}"

`github_delete_commit_comment_reaction`

Delete a reaction from a commit comment.

github_delete_commit_comment_reaction(
  api_token: "<your_github_token>",
  repo_owner: "octocat",
  repo_name: "Hello-World",
  comment_id: 123456,
  reaction_id: 12345
)

GitHub API Plugin for Fastlane

Table of Contents

Getting Started

Requirements

About github_api

Key Features

Available Actions

Issues

Pull Requests

Repositories

Reactions

Return Values

Authentication

Token Permissions

Example

Sample Usage

Run tests for this plugin

Issues and Feedback

Troubleshooting

Common Issues

Authentication Problems

Rate Limiting

Using fastlane Plugins

About fastlane

Complete Action Reference Guide

Issues

github_add_assignees

github_add_labels

github_create_issue

github_get_issue

github_update_issue

github_list_issues

github_add_issue_comment

github_list_issue_comments

Pull Requests

github_create_pull

github_get_pull

github_update_pull

github_list_pulls

github_merge_pull

github_check_pull_merged

github_list_pull_commits

github_list_pull_files

Repositories

github_create_repository

github_delete_repository

github_list_repo_labels

github_create_label

github_update_label

github_delete_label

github_list_milestones

github_create_milestone

github_update_milestone

github_delete_milestone

Reactions

github_create_issue_reaction

github_list_issue_reactions

github_delete_issue_reaction

github_create_issue_comment_reaction

github_list_issue_comment_reactions

github_delete_issue_comment_reaction

github_create_pull_comment_reaction

github_list_pull_comment_reactions

github_delete_pull_comment_reaction

github_create_commit_comment_reaction

github_list_commit_comment_reactions

github_delete_commit_comment_reaction

`github_add_assignees`

`github_add_labels`

`github_create_issue`

`github_get_issue`

`github_update_issue`

`github_list_issues`

`github_add_issue_comment`

`github_list_issue_comments`

`github_create_pull`

`github_get_pull`

`github_update_pull`

`github_list_pulls`

`github_merge_pull`

`github_check_pull_merged`

`github_list_pull_commits`

`github_list_pull_files`

`github_create_repository`

`github_delete_repository`

`github_list_repo_labels`

`github_create_label`

`github_update_label`

`github_delete_label`

`github_list_milestones`

`github_create_milestone`

`github_update_milestone`

`github_delete_milestone`

`github_create_issue_reaction`

`github_list_issue_reactions`

`github_delete_issue_reaction`

`github_create_issue_comment_reaction`

`github_list_issue_comment_reactions`

`github_delete_issue_comment_reaction`

`github_create_pull_comment_reaction`

`github_list_pull_comment_reactions`

`github_delete_pull_comment_reaction`

`github_create_commit_comment_reaction`

`github_list_commit_comment_reactions`

`github_delete_commit_comment_reaction`