GitHub v2

Provides integration with GitHub, a platform for hosting Git repositories and collaborating on code. Teams use GitHub to manage repositories, issues, pull requests, releases, GitHub Actions workflows, and organization members and permissions.

The Node connects to the GitHub REST API (version 2022-11-28). It can read repositories, issues, pull requests, commits, Actions runs and other resources, and create, update or delete them, for example to open issues, comment on pull requests, dispatch Actions workflows or manage organization members. Use it to sync GitHub activity with other systems or to automate repository administration from a Workflow.

Revision History

0.0.0.1 - Initial release.

Connection

The Connection stores the GitHub OAuth App details and the access token obtained when you click Connect your Account. All Methods use it. You can also supply a personal access token directly instead of connecting through an OAuth App.

Setup Notes

Run this Node on a Cloud Runtime.

To connect through an OAuth App:

1. In GitHub, open Settings → Developer settings → OAuth Apps and create an OAuth App.
2. Set the app's Authorization callback URL to the Flowgear OAuth callback URL, https://app.flowgear.net/r/auth. GitHub OAuth Apps allow only one callback URL.
3. Copy the app's client ID and generate a client secret.
4. In the Connection, enter ApplicationName, ClientId and ClientSecret, then click Connect your Account and sign in to GitHub.

Connect your Account requests the repo, admin:org, user, notifications and workflow scopes. Operations that need other scopes, for example gists, packages, Codespaces or deleting repositories, remain available but return a GitHub error until you supply a token with those scopes.

To use a personal access token instead, enter ApplicationName and paste the token into AccessToken. ClientId and ClientSecret are not needed. Grant the token the repository and account permissions that your Workflows need.

GitHub OAuth App tokens do not expire and have no refresh token. If GitHub rejects the token, reconnect the Connection or supply a new token.

Methods

The Node groups the GitHub REST API into four Methods by HTTP verb. In each Method, you choose a template that selects the operation and fills OperationId, Options and, where needed, Items. Options and Items use GitHub's own parameter and field names, such as owner, repo and issue_number.

The Node handles paging itself. It always requests 100 rows per page and follows GitHub's next-page links, so templates have no page, per_page or cursor fields. The first page, or the first item of a mutation, is sent while the Node runs. Later pages and items are sent as the next Node reads the results.

Query

Reads GitHub resources through any of GitHub's GET operations, with automatic paging.

Query templates fill route values, such as owner and repo, with samples against public GitHub resources such as octocat/Hello-World, so a read runs as selected. Query filters show a sample but have no value until you set one. Replace the samples with your own values.

Rows have the following shapes:

• List responses wrapped in a count, such as search results and Actions runs, return one row per element. total_count and incomplete_results are not included.
• Objects that contain paged lists alongside other data, such as a commit comparison, return the whole object as one row per page.
• Text and HTML responses, such as rendered Markdown, return { "Content": "..." }. Lists of plain strings, such as gitignore template names or repository topics, return one { "Value": "..." } row per string.
• Download operations, such as archives, logs, artifacts and release assets, return { "Location": "..." } with the download URL instead of the file.
• Yes/no checks, such as checking whether a repository is starred, a pull request is merged or a user is a collaborator, return one row: { "IsTrue": true } or { "IsTrue": false }. You can use this to branch a Workflow on the answer.

A query that matches nothing returns no rows. If GitHub rejects a read, the Node raises GitHub's error instead of returning an empty result.

Create

Creates GitHub resources and runs GitHub POST actions, such as creating issues, rendering Markdown, dispatching Actions workflows and merging pull requests.

The Flowgear object contains:

• IsSuccess: whether GitHub accepted the request.
• Message: the outcome, or GitHub's error message, validation errors and HTTP status when the item failed. For example, Validation Failed: Issue.title missing_field (HTTP 422).
• Request: the original input item.

A failed row also keeps GitHub's error fields, such as message and documentation_url.

Update

Updates or replaces GitHub resources through GitHub's PUT and PATCH operations.

Delete

Deletes or removes GitHub resources through GitHub's DELETE operations.

Usage Notes

• Create, Update and Delete templates leave route values such as owner and repo empty, so a template can't change anything as selected. Operations with nothing to leave empty, such as marking every notification read, require Confirm to be true instead.
• Items is the request body, and the Node sends one request per item. Operations without a body run once from Options when Items is not connected, and fail if Items is connected.
• When GitHub rejects one item, for example with a validation or permission error, that item returns a failed row and the Node continues with the next one. Failures that would affect every remaining item stop the Node instead. These are a rejected token, a rate limit that can't be retried, or GitHub being unreachable.
• Rate limits that GitHub asks you to wait 60 seconds or less for are retried automatically. Longer waits, such as an exhausted hourly limit, fail immediately with the time the limit resets.
• String and integer lists are CSV text in both directions. Values that contain commas, quotes or line breaks are quoted with doubled quotes, and empty text is an empty list. Free-form provider fields are JSON text.

Known Issues

• GitHub returns 404 Not Found, not 403 Forbidden, when your token can't access a resource. This hides private resources from accounts without access. A "not found" error can therefore mean that the owner, repository or resource doesn't exist, or that the Connection's token lacks permission to see it. Check the spelling first, then check that the token has the required scopes and that the account has access to the organization or repository.
• For the same reason, a yes/no check returns { "IsTrue": false } when the target doesn't exist or the token can't see it.
• Path values that contain /, such as a file path like docs/README.md or a reference like heads/main, are encoded as %2F. Confirm that nested paths behave as expected before you rely on them.
• GitHub App operations that require a JSON Web Token, and deprecated operations, are not available.

See also

• GitHub REST API documentation
• Rate limits for the GitHub REST API
• Create a Connection
• Handle Partial Batch Failures