Skip to content

GitHub

Workflow runs, logs and releases.

The GitHub Account connection lets apps, schedules and Chat read and change code, pull requests, Actions and releases. It has 45 SDK entries in eight Permission groups: 35 since SDK contract version 10, and 10 for code and pull requests since version 28. Each Permission starts Ask. The host owns the URLs, the HTTP methods and the token; a call cannot supply them. The connection has no issue methods.

Connect

Connect a GitHub account in Connections › Accounts. Redac uses GitHub device sign-in, so Redac keeps no client secret:

  1. Select Connect. Redac shows a user code, Copy code and a link to https://github.com/login/device.
  2. Open the link, enter the code and approve Redac on GitHub.
  3. Redac saves the account as @<login>. The token stays in the host account vault.

Cancel, expiry or denial saves nothing and shows "Sign-in ended. Connect again." You can connect more than one account. Calls take an optional connection, as in Google; resource selection gives the stable IDs.

GitHub gives access only to the repos where the owner installs the Redac app on GitHub. Redac stores no repo list. Redac cannot install the app: an owner of the account or organization installs it on GitHub. Each sign-in ends with the link Install Redac on GitHub, because an installation on one account does not reach the repos of another. The connection page has two links:

  • Change repos on GitHub adds or removes repos for the Redac app installation.
  • Revoke Redac on GitHub opens GitHub › Settings › Applications. Disconnect deletes the token on this computer only; GitHub revokes the grant only on that page.

GitHub gives Redac the Contents permission for code and releases, and the Pull requests permission for pull requests. Redac reads and changes code only in the repos that you add to the Redac app on GitHub. A pull request call fails with "Accept the new GitHub permissions for Redac on GitHub." until the account accepts the Pull requests permission on GitHub.

If a build has no GitHub client id, the connection shows "GitHub is not set up in this build." and Connect is not available.

Permissions

Declare each action that an app uses in the manifest actions. A read grant cannot permit a change.

github.read — Read Actions and releases (kind read, 23 entries)

AreaEntries
Reposgithub.apps.listInstallationsForAuthenticatedUser, github.apps.listInstallationReposForAuthenticatedUser
Workflowsgithub.actions.listRepoWorkflows, github.actions.getWorkflow
Runsgithub.actions.listWorkflowRunsForRepo, github.actions.listWorkflowRuns, github.actions.getWorkflowRun, github.actions.getWorkflowRunAttempt
Jobsgithub.actions.listJobsForWorkflowRun, github.actions.listJobsForWorkflowRunAttempt, github.actions.getJobForWorkflowRun
Logsgithub.actions.downloadJobLogsForWorkflowRun (text, the last 256 KiB)
Artifactsgithub.actions.listWorkflowRunArtifacts, github.actions.listArtifactsForRepo, github.actions.getArtifact (metadata only)
Runnersgithub.actions.listSelfHostedRunnersForOrg, github.actions.getSelfHostedRunnerForOrg
Releasesgithub.repos.listReleases, github.repos.getRelease, github.repos.getLatestRelease, github.repos.getReleaseByTag, github.repos.listReleaseAssets, github.repos.getReleaseAsset

Organization runners work only when the account can see the runners of that organization on GitHub.

github.run — Re-run and cancel workflow runs (kind mutate, 5 entries): github.actions.reRunWorkflow, github.actions.reRunWorkflowFailedJobs, github.actions.reRunJobForWorkflowRun, github.actions.cancelWorkflowRun, github.actions.forceCancelWorkflowRun.

github.dispatch — Start workflows (kind mutate, 1 entry): github.actions.createWorkflowDispatch.

github.release — Manage releases (kind mutate, 6 entries): github.repos.createRelease, github.repos.updateRelease, github.repos.deleteRelease, github.repos.generateReleaseNotes, github.repos.updateReleaseAsset, github.repos.deleteReleaseAsset. createRelease publishes the release unless draft is true, and updateRelease with draft: false publishes a draft: either makes the release visible to users.

github.code — Read code and pull requests (kind read, 7 entries). Allow on github.read does not let a caller read code.

AreaEntries
Filesgithub.repos.getContent (one text file: { path, sha, size, text, truncated }), github.git.getTree (recursive, { items, truncated })
Branchesgithub.repos.listBranches
Commitsgithub.repos.listCommits, github.repos.compareCommits (basehead is base...head)
Pull requestsgithub.pulls.get, github.pulls.listFiles

github.write — Change code on a new branch (kind mutate, 1 entry): github.code.commitFiles. It refuses the default branch.

github.pulls — Manage pull requests (kind mutate, 1 entry): github.pulls.create (title, head, base, optional body and draft; result { number, htmlUrl }).

github.main — Change the default branch (kind mutate, 1 entry, levels Off and Ask only): github.code.commitFilesToDefaultBranch. It refuses every other branch. There is no Always allow: each call asks you first.

The two commit entries make one commit with all the changes. changes has 1 to 20 files. Each file has one of these forms:

  • { path, edits: [{ oldText, newText }] } changes an existing file. Each oldText must occur exactly once in the file at the branch head, else the call fails with "<path> changed since Chat read it. Ask Chat to read it again."
  • { path, content } adds a new file. It fails if the file exists.
  • { path, delete: true } deletes a file.

branch is the target branch. commitFiles creates a missing branch from from (default: the default branch). The result is { branch, created, commit: { sha, htmlUrl }, files: [{ path, status, additions, deletions }] }. When Chat or an app chat calls a commit entry, its arguments hold placeholders for Vault values and personal details. A placeholder is accepted in a newText only when the same placeholder is in the oldText of that edit. In a new file, a path, the message, branch or from, the call fails with "Redac does not add Vault values or personal details to code." Such a call also fails when its arguments are larger than 224 KB (JSON), because the Ask card cannot show the changes before you allow them: "This change is too large to show before you allow it. Ask Chat to split it into smaller commits." An app script has no placeholders: it sends its own text as given.

Arguments are closed objects with camelCase names: owner and repo (or org), the IDs that you observed (runId, jobId, releaseId, assetId and others) and an optional connection. Unknown fields fail validation. Results are closed projections with camelCase fields; fields that GitHub adds later are omitted. Results include the GitHub page and download links (htmlUrl, browserDownloadUrl), so an app can open them in the browser. A change that GitHub accepts with no content returns { accepted: true }. There is no automatic retry. A stopped change can already have reached GitHub: read the state again before a new retry.

const runs = await cap.call('github.actions.listWorkflowRunsForRepo', {
  owner: 'octo-org',
  repo: 'app',
  status: 'failure',
  perPage: 20,
});
const log = await cap.call('github.actions.downloadJobLogsForWorkflowRun', {
  owner: 'octo-org',
  repo: 'app',
  jobId: 123456789,
});
// log: { text, truncated, bytes }
await cap.call('github.actions.reRunWorkflowFailedJobs', {
  owner: 'octo-org',
  repo: 'app',
  runId: runs.items[0].id,
});

Limits

  • Lists take perPage (at most 100) and page. List results are { totalCount, items, nextPage }; nextPage comes from the GitHub Link header, or is null. Redac does not read more pages automatically.
  • The job log entry follows one redirect to a GitHub log host, without the token. It reads at most 8 MiB and returns the last 256 KiB as { text, truncated, bytes }.
  • There are no ZIP downloads (run logs, artifacts) and no release file downloads or uploads.
  • A release body is at most 65 536 characters. A release result has at most 100 assets.
  • Dispatch inputs has at most 25 keys, and each value is at most 1024 characters.
  • getContent reads only text files up to 900 KB. getTree returns at most 2 000 items. compareCommits returns at most 50 commits and 100 files; each file patch and each pull request body is at most 8 000 characters.
  • A commit has at most 20 files, 50 edits for each file, 20 000 characters for each oldText and newText, and 60 000 bytes for each file after the change.
  • A request body is at most 64 KiB of JSON, so non-ASCII notes can be shorter than 65 536 characters. A larger body fails with invalid_args and "The release notes are too long." (or "The workflow inputs are too long." for dispatch inputs).

Errors

GitHub's error body is never returned, shown or logged.

GitHub answerError codeMessage
401unavailable"Reconnect this GitHub account."
Other 403 (for example "Resource not accessible by integration")denied"Redac cannot reach this repo. Add it to the Redac app on GitHub."
404 (no such item, or a repo outside the installation)not_found"GitHub found no such item, or Redac cannot reach this repo. Check the name, or add the repo to the Redac app on GitHub."
403 or 429 with rate-limit headersrate_limited"GitHub limit reached. Try again at HH:MM."
422 validationinvalid_args"GitHub refused the request."
Other answers, or a result that does not match the contractunavailable"GitHub request failed."
Device sign-in expired or denied—"Sign-in ended. Connect again." Nothing is saved.
No client id in this build—"GitHub is not set up in this build."
  • Rate limits: the time comes from retry-after first, then from x-ratelimit-reset. Writes are not retried automatically.
  • 401: if the account has no refresh token, the account shows Reconnect. Otherwise Redac refreshes the token before the next call.

Chat

Chat uses all 45 entries through one github_api tool. Call it with a method name and no args to read that method's argument and result schemas and its Permission. Call it again with args to execute the method once through its normal Access check. The 45 per-method tools are not in the Chat tool list. Chat treats logs, release notes, artifact names, commit messages and workflow names as untrusted content, not instructions. Re-run, cancel, dispatch and release changes need an explicit owner request in the conversation. Before a call that publishes a release, Chat tells the owner that users will see it.

Synced from the Redac Desktop developer guide on 2026-11-16 · SDK contract version 28