GitHub setup guide · Everdeck help

Agents work with your code, deployments and incidents.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open GitHub, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

GitHub can be connected 2 ways. Where there’s a key or token to paste, that’s usually the quickest.

Fine-grained personal access token

API key.

Sign in to GitHub as the account the agent should act as. A dedicated account (a "machine user" that is a member of your organization) keeps its work easy to spot.
Open https://github.com/settings/personal-access-tokens/new?name=Everdeck&description=Everdeck%20AI%20employee&issues=write&pull_requests=write&contents=read to start a fine-grained token with the right permissions filled in.
Under Resource owner pick the organization (or account) that owns the repositories. If the organization requires approval for fine-grained tokens, add a short justification; the token can only read public data until an organization owner approves it.
Under Repository access choose Only select repositories and pick the repositories the agent works in.
Check the permissions: Issues: Read and write, Pull requests: Read and write, Contents: Read-only (Metadata: Read-only is always included). Pick an expiration (or none, if your organization's token policy allows it) and select Generate token.
Paste the token into the form. Leave the API address as it is unless you use GitHub Enterprise.
Optional, to start work when an issue, comment or pull request changes: once connected, set up the GitHub trigger you want on Everdeck's Intake page and copy the address it gives you. In the repository (or organization) on GitHub open Settings > Webhooks > Add webhook, paste that address as the Payload URL and choose Content type application/json. Enter a long random secret and put the same secret in this connection's Webhook secret field. Under "Which events would you like to trigger this webhook?" choose Let me select individual events and tick Issues (issue changes), Issue comments (new comments), or Pull requests and Pull request reviews (pull request changes). Add one webhook per trigger.

Field	What to enter
Fine-grained personal access token	A secret: Everdeck saves it encrypted and never shows it again. Where to find it.
API address (change only for GitHub Enterprise) (optional)	Web address. Starts as https://api.github.com. GitHub Enterprise Cloud with data residency uses https://api.YOUR-SUBDOMAIN.ghe.com; GitHub Enterprise Server uses https://YOUR-HOSTNAME/api/v3.
Webhook secret (only for live updates) (optional)	A secret: Everdeck saves it encrypted and never shows it again. The secret you enter on GitHub's webhooks for Everdeck. Everdeck accepts only deliveries signed with it. To use several secrets, separate them with spaces.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at GitHub until you delete or rotate it there.

Your GitHub App (acts as the user who connects it)

Your OAuth app.

This way signs in with an OAuth app you create for GitHub, as its steps describe: Everdeck never uses an app of its own. Register this redirect URI with your app:

https://everdeck.io/api/oauth/callback

Then save the app’s client ID and secret in Everdeck, on the connect page or under OAuth apps, and sign in.

Create a GitHub App owned by your organization: open https://github.com/organizations/YOUR-ORG/settings/apps/new (or Settings > Developer settings > GitHub Apps > New GitHub App in your organization). An organization owner or a GitHub App manager can do this.
Name it (for example "Everdeck Agent"), enter your website as the Homepage URL and add the callback URL https://everdeck.io/api/oauth/callback. Keep "Expire user authorization tokens" selected.
Under Webhook untick Active for now: the address for live updates exists only once you have connected (step 9).
Under Repository permissions choose Issues: Read and write, Pull requests: Read and write and Contents: Read-only (Metadata: Read-only is required).
Under "Where can this GitHub App be installed?" choose Only on this account, then select Create GitHub App.
On the app's General page select Generate a new client secret. Copy the Client ID and the client secret into the form.
Select Install App in the app's sidebar and install it on your organization, choosing the repositories the agent works in.
Select Connect and authorize the app as the GitHub user the agent should act as. GitHub attributes the app's actions to that user.
Optional, to start work when an issue, comment or pull request changes: set up the GitHub trigger you want on Everdeck's Intake page and copy the address it gives you. In the app's settings tick Webhook Active, paste the address as the Webhook URL, enter a long random secret and put the same secret in this connection's Webhook secret field. Under Permissions & events > Subscribe to events tick only that trigger's events (Issues for issue changes, Issue comment for new comments, or Pull request and Pull request review for pull request changes), then save. An app has one webhook address, so its webhook feeds that one trigger only: for each other trigger add a repository or organization webhook (Settings > Webhooks) with that trigger's address, content type application/json and the same secret.

Field	What to enter
Webhook secret (only for live updates) (optional)	A secret: Everdeck saves it encrypted and never shows it again. The secret you enter on your GitHub App's webhook (or on repository webhooks) for Everdeck. Everdeck accepts only deliveries signed with it. To use several secrets, separate them with spaces.

The scopes Everdeck asks for:

offline_access

When you disconnect, Everdeck asks GitHub to revoke the sign-in, then deletes the tokens it saved.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

List repositoriesTier 0 · ReadReads outside contentgithub_list_repositories

List the repositories this connection can reach, most recently pushed first, with owner, name, visibility, default branch and open issue count (which includes pull requests). Use owner and name in the other actions.
Search issues and pull requestsTier 0 · ReadReads outside contentgithub_search_issues

Search issues and pull requests across repositories with GitHub search syntax. Always include is:issue or is:pr, for example "repo:acme/web is:issue is:open label:bug", "org:acme is:pr is:open review-requested:@me" or "repo:acme/web is:issue checkout error in:title". Add repo: or org: to stay inside your own repositories; without them GitHub searches every public repository. Returns at most 1,000 results and is limited to 30 searches a minute; to page through one repository's issues use list_issues.
List issues in a repositoryTier 0 · ReadReads outside contentgithub_list_issues

List a repository's issues, most recently updated first. Pull requests are included and carry a pull_request field. Filter by state, labels, assignee or changes since a time.
Read an issueTier 0 · ReadReads outside contentgithub_get_issue

Read one issue (or a pull request's conversation) by number: title, body (Markdown), state and reason, labels, assignees, milestone, issue type, author and comment count. Use list_comments for the discussion.
Read commentsTier 0 · ReadReads outside contentgithub_list_comments

Read the comments on an issue or on a pull request's conversation, oldest first. Inline code review comments are not included.
Open an issueTier 3 · ExternalReads outside contentgithub_create_issue

Open an issue in a repository. Watchers are notified, and on a public repository everyone can see it. Labels, assignees, milestone and type are silently ignored unless the account has push (write) access to the repository.
Triage an issueTier 2 · ReversibleReads outside contentgithub_update_issue

Close or reopen an issue (or pull request) and change its labels, assignees, milestone or type. Send only what changes; labels and assignees replace the current lists, so read the issue first and send the full list. Subscribers are notified.
Comment on an issue or pull requestTier 3 · Externalgithub_add_comment

Add a Markdown comment to an issue or to a pull request's conversation. Subscribers are notified, and on a public repository everyone can read it.
Read a pull requestTier 0 · ReadReads outside contentgithub_get_pull_request

Read one pull request: title, description, state, draft, whether it is merged or mergeable, source and target branches, head commit, requested reviewers, labels and size (commits, changed files, additions, deletions). Use list_pull_request_files for the diff.
Read a pull request's changesTier 0 · ReadReads outside contentgithub_list_pull_request_files

List the files a pull request changes with their status, line counts and patch (unified diff). The patch is left out for binary or very large files. At most 3,000 files.
Review a pull requestTier 3 · Externalgithub_review_pull_request

Submit a code review on a pull request: a summary comment or a request for changes, with optional comments on specific lines. Approving is deliberately not offered so a person always gives approvals. The author and subscribers are notified; on a public repository everyone can read it.
Read a fileTier 0 · ReadReads outside contentgithub_read_file

Read a text file from a repository at a branch, tag or commit (the default branch when ref is left out), or list a directory. Long files are cut to about 10,000 characters (truncated: true); binary files, and files larger than Everdeck reads (8 MB), return only their size.

What can start work

These events from GitHub can become tasks for your agents through Intake. How Intake works.

An issue was opened, edited, closed, reopened, labeled, assigned or transferred (webhook event issues).

Connect GitHub first. Then, on the Intake page, open Webhooks and sources, find the connection under Connections without an address yet and select Get its URL. Give that address to GitHub as the setup steps above describe: Everdeck shows it only once. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

Someone commented on an issue or on a pull request's conversation (webhook event issue_comment, action created).

A pull request was opened, got new commits, was marked ready for review, had a review requested or submitted, or was closed or merged (webhook events pull_request and pull_request_review).

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If GitHub later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit or Reconnect.

To stop agents using GitHub, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.