GitHub v2

Provides integration with GitHub, a platform for hosting Git repositories where teams track issues, review pull requests, publish releases, run GitHub Actions workflows, and manage organization members and permissions.

Use templates to select operations from the GitHub REST API (version 2022-11-28). For example, you can read commits and Actions runs, open issues, comment on pull requests or start Actions workflows. Use these operations to synchronize GitHub activity with other systems or automate repository administration from a Workflow.

Revision History

0.0.0.1 - Initial release.
0.0.0.6 - Each item can now set the operation's route values, such as owner, repo or issue_number, so one step can change different records without a For Each. Operations without a request body, such as most deletes, accept items that carry only route values.

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.

Property Type Description
ApplicationName String The OAuth App name. GitHub requires every request to identify the application, so this value is sent as the User-Agent header. Required.
ClientId String Client ID of the GitHub OAuth App. Required for Connect your Account only.
ClientSecret Masked Client secret of the GitHub OAuth App. Required for Connect your Account only.
AccessToken Masked GitHub access token obtained through Connect your Account, or a personal access token supplied directly.
TimeoutSeconds Integer Per-request timeout in seconds. The default is 30.

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 requests 100 rows per page and follows GitHub's next-page links automatically. Templates therefore have no page, per_page or cursor fields.

The Node completes the first read or write before returning the output stream. It processes later pages and items as the next Node reads the results.

Query

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

Query templates prefill route values such as owner and repo with public GitHub resources, for example octocat/Hello-World. You can run the query with those values or replace them with your own. Query filters show examples, but you must enter a value to apply a filter.

Parameter Type Description
Connection Connection GitHub Connection.
OperationId String Operation selected from a template.
Options Object Route and query values using GitHub's parameter names. Paging is handled by the Node.
Return Type Description
Response Array One row per collection element, or one row for a single-object read.

The fields in each row depend on the response:

  • Responses containing a list and count fields, such as search results and Actions runs, return one row per list item. 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.

Parameter Type Description
Connection Connection GitHub Connection.
OperationId String Operation selected from a template.
Options Object Route and query values using GitHub's parameter names. Route values are used for items that do not set their own.
Items Array One request per item. Each item holds the request body and can also set the operation's route values, such as issue_number, to target its own record. Required where GitHub requires a body.
Confirm Boolean Set to true to run an operation that has no route values, such as marking every notification read. Not needed when Items is connected.
Return Type Description
Response Array One row per input item with GitHub's response and a Flowgear object, or one row for an operation run without Items.

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.

Parameter Type Description
Connection Connection GitHub Connection.
OperationId String Operation selected from a template.
Options Object Route and query values using GitHub's parameter names. Route values are used for items that do not set their own.
Items Array One request per item. Each item holds the request body and can also set the operation's route values, such as issue_number, to target its own record. Required where GitHub requires a body.
Confirm Boolean Set to true to run an operation that has no route values. Not needed when Items is connected.
Return Type Description
Response Array One row per input item with GitHub's response and a Flowgear object (IsSuccess, Message and Request), or one row for an operation run without Items.

Delete

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

Parameter Type Description
Connection Connection GitHub Connection.
OperationId String Operation selected from a template.
Options Object Route and query values using GitHub's parameter names. Route values are used for items that do not set their own.
Items Array Optional. One request per item, each naming the record to delete through the operation's route values, such as owner, repo and issue_number. Deletes that take a body also read the body from the item.
Confirm Boolean Set to true to run an operation that has no route values. Not needed when Items is connected.
Return Type Description
Response Array One row per input item with a Flowgear object (IsSuccess, Message and Request), or one row for an operation run without Items.

Route Values on Items

Create, Update and Delete let each item set the operation's route values, such as owner, repo or issue_number. This lets one step comment on, label, close or delete many different records without a For Each.

  • An item's value applies to that item's request only. Items that leave it out, or set it to null, use the value in Options, so you can leave the Options route value empty when every item has its own.
  • Route values are sent in the URL only, not in the body sent to GitHub. Flowgear.Request still shows the whole item.
  • A route value must be text, a number or a boolean. If it is missing from both the item and Options, is empty, is . or .., or is an object or a list, that item returns Flowgear.IsSuccess set to false. GitHub is not called for that item, and the remaining items still run.
  • For operations without a request body, such as most deletes, starring a repository or following a user, items carry only route values. An item with any other field that is not null fails, so a misspelt route value can't fall back to the record named in Options.
  • Items of operations that take a body can carry fields GitHub does not list, and those fields are sent in the body. A misspelt route value on such an item, for example pth instead of path, is therefore sent as a body field and the request goes to the record named in Options. When items name their own records, leave the Options route value empty so that an item without a valid route value fails instead.
  • If a route value has the same name as a field in the request body, the body field is kept and the route value comes from Options only. For example, when updating an Actions variable, the item's name is the new name and Options.name is the current one.
  • Query values, such as name on the release asset upload, always come from Options.
  • Two operations have neither a request body nor route values and still reject Items: revoking the installation access token and removing your interaction restrictions.
  • Templates list the route values under Items with a sample but no value. Refresh the template in existing Create, Update and Delete steps to see them.
  • If your items already contain a field with the same name as a route value, that field now selects the record for the item.

Usage Notes

  • Before running Create, Update or Delete, fill in the route values, such as owner and repo, that the template leaves empty, either in Options or on each item. For operations with no required route values, options or request body, such as marking every notification read, set Confirm to true when running without Items.
  • The Node sends one request per item. Without Items connected, an operation runs once from Options.
  • 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. Check Flowgear.IsSuccess before running work that depends on a successful write.
  • Failures that would affect every remaining item stop the Node. Examples include a rejected token, a rate limit that can't be retried, or GitHub being unreachable.
  • The Node automatically retries rate-limited requests when GitHub specifies a wait of 60 seconds or less. Longer waits, such as an exhausted hourly limit, fail immediately with the time the limit resets.
  • String and integer lists use comma-separated values (CSV) in requests and responses. Enclose values containing commas, quotes or line breaks in double quotes, and double any quotes inside a value. Empty text represents an empty list. Free-form GitHub fields use 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