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. Twenty-eight 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.

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. The webhook signing secret for triggers is configured separately, per trigger, when you publish a workflow.

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.

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

Every trigger is a real-time webhook. Each inbound delivery is one event and produces one activation. There is no polling and no batch or digest collapse.

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. See Triggers and actions.

Issues and discussions

Pull requests

Code and releases

Builds and deployments

Repository administration and security

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

Each trigger verifies every delivery against an HMAC-SHA256 signature in the X-Hub-Signature-256 header. When you publish a trigger, TaskJuice gives you a signing secret. Paste it into the GitHub webhook's configuration under Secret. GitHub signs the raw request body and sends the hex digest in that header. Deliveries whose signature does not match are rejected before the workflow runs.

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

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.

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}}.

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.
• A webhook signing secret is required for every trigger. Deliveries without a valid X-Hub-Signature-256 signature are rejected.
• 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 is not covered. GitHub exposes Projects v2 only through its GraphQL API, which this integration does not use.
• 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.
• Triggers are real-time and single-event. Each webhook delivery is one activation. There is no polling, batching, or digest mode.