GitHub app

Connect a GitHub organisation or account to post repository events into channels, create issues with /issue, re-run failed checks from a post, and turn github.com links into cards.

Before you start

• Plans. Available on every plan. Self-hosted servers have every feature on.
• Who. Connecting, routing and disconnecting need the Manage integrations permission (Owners, Admins, or a custom role that grants it). On GitHub, you need to be able to install apps on the account you connect.
• A browser. Connecting goes through GitHub's pages, so do it in a web browser rather than the desktop app.

Needs setup on the server. This integration appears only when the server's operator has registered a GitHub App. Until then the GitHub section says Not set up on this server. On the hosted service, ask us at [email protected]; on your own server, see the self-hosting configuration guide.

GitHub app or incoming webhook?

The plain incoming webhook works on every server with no setup: you paste a URL and a secret into one repository's webhook settings, and its events post into one channel. The GitHub app is set up once per GitHub account, then routed in Missived:

Both work side by side; an org can use either or both.

Connect GitHub

1. Open Org Settings → Integrations → GitHub → Connect GitHub.
2. On GitHub's page, pick the organisation or account, choose which repositories the app can see, and choose Install & Authorize.
3. GitHub sends you back to the Integrations page, with the account and its repositories listed.

Already installed the Missived app from GitHub's own page? Choose Link an existing installation instead. GitHub asks you to authorise the app, then you come back and pick the account.

To connect a second GitHub account, choose Connect another account. Each GitHub installation belongs to one Missived org.

If you aren't an owner of the GitHub organisation, GitHub sends its owners a request instead. Once they have installed the app, use Link an existing installation.

Route a repository to a channel

Under the account, choose Add a route:

Choose Add route. The org's GitHub bot joins the channel, so its buttons and /issue work there. A channel can have several routes, and one repository can post to several channels.

Each route has Pause / Resume, Edit and Remove.

What it posts

Events arrive within seconds as cards from the GitHub bot (with a BOT badge). Every card has an Open link (Open commit or Compare, Open pull request, Open issue, Open comment, Open release, Open run), and some have a button:

• An open pull request has Re-run checks: it re-runs the failed jobs of the pull request's failed workflow runs.
• A failed workflow run has Re-run failed jobs.

The answer is a private reply only you see, such as "Re-running the failed jobs of that run in acme/web." Approving and merging are not offered.

/issue

In a channel with a routed repository, type /issue. Options:

• title: the issue's title (you can change it on the form).
• repo: owner/name, needed when the channel has more than one repository.

A form opens with Title and Description. Submit it and the issue is created on GitHub by the Missived app. Its body ends with "Opened from Missived by name in #channel", and you get a private "Created owner/repo#123" reply with an Open button.

Who may use /issue and the buttons

Under the account, Who may create issues with /issue and press Re-run:

• Anyone who can post in the channel (the default), or
• Only people with Manage integrations.

Either way, a button or /issue works only for a repository routed to that channel.

Link cards

A github.com link to an issue, a pull request, a commit or a repository of a connected account becomes a card showing its state, branches, changes and labels.

• A private repository's card is shown only in a channel that has a route for that repository.
• A public repository's card can show in any channel apps may be in.
• Never in a direct message, group chat or personal channel.

Any other link gets the ordinary link preview.

Manage and disconnect

Each connected account has:

• Refresh repositories and Manage on GitHub ↗ (change which repositories the app can see; Missived updates its list when you come back).
• Recent deliveries: the last 50 events from GitHub and what happened to each: Posted, Left out (a filter), No route, Ignored, Throttled or Failed.
• Disconnect: its routes stop and are removed; past posts stay. The app stays installed on GitHub until someone uninstalls it there.

Uninstalling the app on GitHub disconnects it in Missived too. Every change appears in the org's Audit log, never with an issue's title or body.

What data moves

• From GitHub: the repository events the app is subscribed to, the list of repositories it can see, and, for link cards and buttons, the details of that issue, pull request, commit, repository or workflow run.
• To GitHub: the issues people create with /issue (title, description and the "Opened from Missived by…" line), and re-run requests. Nothing else about your org or its members.
• Stored in Missived: the connected account, its repository names, your routes and settings, and a status line for each recent delivery (never its body). The GitHub sign-in used to prove you can see the installation is revoked straight away and never stored. Avatars are shown through Missived's image proxy.

Limits

• At most 60 posts a minute per connected account; past that, a delivery is logged as Throttled.
• Branch and label filters: up to 20 each per route.
• Issue titles up to 256 characters, descriptions up to 4,000.

Troubleshooting