GitHub integration

What it does

The GitHub integration turns repository activity into automation you run on behalf of your clients. Connect a Personal Access Token once, then read and write issues, pull requests, reviews, labels, milestones, releases, files, and GitHub Actions runs from any workflow step. Thirty-three real-time triggers let you react the moment an issue changes, a pull request moves through review, a build finishes, or a security alert opens, and three polling triggers watch the corners GitHub publishes no webhook for.

Typical uses: open an issue when a support ticket is escalated, post a Slack summary when a pull request is approved, cut a release when a milestone closes, or file a ticket the moment Dependabot reports a high-severity advisory.

GitHub lives under the Developer Tools category. You can also find it by searching for git or gh.

Connect a GitHub account

The connection holds one credential: a Personal Access Token. This integration does not use OAuth, so there is no "Sign in to GitHub" button and no consent screen. Webhook triggers need no secret from you: TaskJuice mints the signing secret when it registers the webhook on publish.

1. Generate a token in GitHub

   Create a fine-grained token at https://github.com/settings/personal-access-tokens, or a classic token at https://github.com/settings/tokens. Grant only the permissions your workflows need. For the actions below that is typically read and write on Contents, Issues, Pull requests, and Actions, plus read on Metadata. If you use webhook triggers, also grant Webhooks: Read and write (fine-grained) or the admin:repo_hook scope (classic), and make sure the account that owns the token is an admin of each repository you pick. Without it, every action works but trigger setup stops with a permission message.

2. Paste it into the connection

   In TaskJuice, open the GitHub connection and paste the token into the Personal Access Token field.

3. Save the connection

   TaskJuice stores the token encrypted. It is not shown again after you save, so keep a copy in GitHub if you need to reference it later.

To revoke access, delete the token in GitHub. Because access is scoped to the token, switching the acting account means generating a new token and rotating it into the connection. For credential lifecycle details, see Connections.

Choosing a repository

Every repository-scoped action takes a single Repository dropdown rather than separate owner and name fields. The list contains every repository your token can reach, across your personal account and all of your organizations, shown as owner/name.

To act on a repository the workflow computes instead of one you pick, use the {} toggle on the field and bind an expression. Trigger payloads carry the value directly, so a common binding is:

{{$trigger.repository.full_name}}

Dependent dropdowns for Label, Branch, and Workflow populate from whichever repository is selected. Select the repository first, then those fields load.

Triggers

Thirty-three of the thirty-six triggers are real-time webhooks. Each inbound delivery is one event and produces one activation, with no batch or digest collapse. The remaining three poll, because GitHub publishes no webhook for what they watch.

Most events fire across many lifecycle transitions. The specific transition arrives in the action field of the output, so add a Branch or Switch node downstream and filter on it, for example action == "opened". Push, Create, Delete, Fork, and Commit Status carry no action field. Wiki Page carries none either: its created-or-edited verb sits per page at pages[].action, so read that rather than action. See Triggers and actions.

Issues and discussions

Pull requests

Code and releases

Builds and deployments

Repository administration and security

Watching outside webhooks

Three triggers poll, because GitHub publishes no repository webhook for what they watch. Each emits one activation per cycle carrying every newly seen record under items, deduplicated by id, and suppresses whatever already existed when you published. Add a Loop node downstream over items to handle records one at a time; leave it off for a digest.

github/new-gist narrows that further: it fires only for gists created after the workflow is first published, judged by the gist's own creation date, so editing a gist that existed before then does not fire it.

Output shape

Every trigger delivers the raw GitHub webhook body. repository and sender are present on all of them. The event subject arrives under its own key, for example issue, pull_request, release, or workflow_run. organization is present when the repository belongs to an organization, and installation only on GitHub App deliveries, so treat both as optional.

Verifying inbound deliveries

You do not create the webhook yourself. Pick a repository in the trigger's Repository field, publish the workflow, and TaskJuice registers a webhook on that repository, mints the signing secret, and subscribes it to exactly the events your published triggers need. Publishing a second trigger on the same repository widens that one webhook rather than adding another.

Every delivery is then verified against an HMAC-SHA256 signature in the X-Hub-Signature-256 header. GitHub signs the raw request body and sends the hex digest; deliveries whose signature does not match are rejected before the workflow runs. Turning the workflow off removes the subscription, and deleting the webhook in GitHub's own settings stops deliveries until you republish.

If registration does not finish

While TaskJuice registers the webhook, the trigger panel shows "Setting up GitHub…". Most failures keep retrying on their own before a message replaces it. A missing permission and a refused repository are the exceptions: their messages show straight away. The ones worth knowing in advance:

• "GitHub accepted the connection but won't let it manage webhooks…" The token works, but it cannot read or create the repository's webhooks. The message quotes GitHub's own reason when GitHub gives one, for example "Resource not accessible by personal access token". Edit the token in GitHub to grant Webhooks: Read and write (fine-grained) or admin:repo_hook (classic), make sure its account is an admin of the repository, then republish. You do not need to reconnect: the token stays the same. If you fix the token and do not republish, TaskJuice re-checks once a day and picks the change up on its own.
• "GitHub refused webhook setup for…" GitHub refused one of your repositories while the others registered normally. The message names the repository and quotes GitHub's reason, for example "Resource not accessible by personal access token". Triggers on your other repositories keep receiving events, and the refused repository is retried on its own. To fix it, give the token webhook access on that repository: Webhooks: Read and write on it (fine-grained) or admin rights on it (classic). If every repository you use is refused, you see the "won't let it manage webhooks" message above instead, or, when GitHub answers that the repository does not exist for the token, the "Automatic setup for GitHub stopped" message below.
• "GitHub rejected the connection. Reconnect your GitHub account, then republish." The token was revoked or has expired. Generate a new one, rotate it into the connection, and republish.
• "Automatic setup for GitHub stopped after repeated failures, and its triggers may not be firing. Contact support." Something has kept failing long enough that waiting is no longer the answer. Assume your GitHub triggers may not be receiving events until it clears.

Actions

All actions authenticate with the token from your connection. Reads accept page and per_page so you control how much comes back on each call. GitHub caps per_page at 100.

Issues

List Issues returns pull requests alongside issues, which is how the GitHub API behaves. To exclude them, filter downstream on the pull_request key: it is present only on rows that are pull requests.

Use Close Issue and Reopen Issue rather than setting state through Update Issue. Keeping state changes in their own actions means an update that only edits a title cannot accidentally reopen a closed issue.

Pull requests

Merge Pull Request accepts an expected head SHA. Supply it when the workflow read the pull request earlier in the run and you want the merge to fail rather than land on top of newer commits. GitHub answers 409 when the head has moved.

Repositories, branches, and commits

Branches and refs

Create Branch takes the whole ref rather than a bare branch name, which is what GitHub's endpoint documents and what lets the same action create tags (refs/tags/v2.1.0). A bare name is rejected.

Files

File contents travel base64-encoded in both directions. Get File Contents returns the body in content with encoding: "base64", and Create or Update File expects base64 in its Content field. To replace an existing file you must supply its current sha, which Get File Contents returns. Omit the sha to create a new file.

Reviews

Get Pull Request Diff and Get Pull Request Patch are the only two actions that do not return JSON. Their output is the diff or patch as a single string, so reference it directly rather than indexing into fields.

Labels, milestones, and releases

Create Release can write the notes for you. Turn on Generate notes and GitHub composes them from the pull requests merged since the previous tag.

Actions and workflows

Run Workflow targets a workflow that already declares a workflow_dispatch trigger in its YAML. If it does not, GitHub answers 404. Create Repository Dispatch is the alternative when you want to trigger work without naming a specific workflow: any workflow listening for repository_dispatch picks it up, and your JSON arrives as github.event.client_payload.

List Workflows, List Workflow Runs, and List Workflow Run Jobs return their items nested under workflows, workflow_runs, and jobs respectively, not as a bare list. Reference them accordingly downstream, for example {{$steps.list_runs.data.workflow_runs}}.

Get Workflow Usage returns an empty billable object for a workflow that has consumed no billable minutes. That is a success, not an error.

Search

Search endpoints carry their own, tighter rate limit than the rest of the API and return results under items.

Gists

Users and organizations

Check Organization Membership succeeds only when the user IS a member. GitHub answers 404 for a non-member, which surfaces as NOT_FOUND rather than a false result, so branch on the step failing rather than on its output.

Repository insights

The four traffic actions require push access to the repository. A read-only token gets 403.

GraphQL

GitHub answers a rejected GraphQL query with HTTP 200 and an errors array rather than an error status. This action treats a response carrying errors as a failure and surfaces GitHub's own message, so a bad query fails the step instead of passing null downstream.

Errors

When a request fails, the step's top-level error code is UPSTREAM_REQUEST_FAILED. GitHub's HTTP status maps to a specific TaskJuice error code:

A 404 on a repository you know exists almost always means the token cannot see it. Check the token's repository access before assuming the name is wrong.

For how a paused or failed run recovers, see Run and step statuses and Reconnect an integration.

Known limitations

• Authentication is a Personal Access Token, not OAuth. Access is limited to the permissions you granted the token. Switching the acting account means generating a new token and rotating the connection.
• Tokens expire. Fine-grained and classic tokens can carry an expiry. When one lapses, requests return 401. Rotate the token to restore the connection.
• Rate limits apply per token. GitHub publishes per-token quotas for authenticated REST requests. Every step records the remaining quota, and a 429 is retried with backoff.
• Reads return one page per step. Set page and per_page and iterate with a Loop node when you need more than one page. This keeps a single step from exhausting your quota on a large repository.
• The repository dropdown lists up to 1000 repositories. Beyond that, bind the field with the {} toggle instead of picking from the list.
• Webhooks are registered for you. Publishing a trigger creates or widens a single webhook on the chosen repository and mints its signing secret. Deleting that webhook in GitHub's settings silently stops deliveries until you republish the workflow.
• Organization-level events are not available. organization, team, membership, and org_block are delivered only by organization webhooks, and this integration registers repository webhooks.
• github.com only. The connection targets api.github.com. There is no host field, so GitHub Enterprise Server is not supported. If you manage projects on a self-managed host, see the GitLab integration.
• Projects v2 has no dedicated actions. GitHub exposes Projects v2 only through its GraphQL API. Reach it with Execute GraphQL Query rather than a purpose-built action.
• Release assets cannot be uploaded. Releases can be created, updated, and deleted, but binary asset upload uses a separate upload host and is not available.
• Webhook triggers are real-time and single-event. Each delivery is one activation, with no batching or digest mode. The three polling triggers are the exception: each emits one activation per cycle wrapping every newly seen record in items.