Crosdesk

Appearance

GitHub ​

Connects this workspace to GitHub, so a pull request that mentions a task links to it by itself. See Linking pull requests for what people write.

Video

All video tutorials

Administrators only. It's under Admin → GitHub.

How it fits together ​

Each workspace has its own GitHub App. You create it once, from this screen, and then install it on the GitHub accounts and repositories whose pull requests should link here.

The app can only read pull requests. It doesn't read code, and writes nothing to GitHub. That's also why a repository admin can install it without needing an organisation owner.

Creating the app ​

  1. Choose who owns the app on GitHub:
    • An organisation, for a team. Type its name as it appears in its GitHub address. You need to be an owner or an app manager in that organisation.
    • My GitHub account, for your own repositories.
  2. Press Create GitHub App. GitHub opens with the app filled in. Confirm it there. If GitHub says the name is taken, change it; names are unique across all of GitHub.
  3. GitHub sends you back here, and the app is ready.

Crosdesk stores the app's private key and secrets encrypted, and never shows them again. There is nothing to copy and paste.

GitHub has to be able to reach Crosdesk. It delivers events to the address shown on the screen, which comes from the installation's PUBLIC_URL. An address like localhost is refused when the app is created. To try this on a laptop, use a tunnel and set PUBLIC_URL to it.

Gate status ​

The app reads pull requests, their reviews, checks and commit statuses — read-only — so a failing CI shows as Gate failed on a pull request. An app created before Crosdesk asked for checks does not have them, and GitHub lets no app grant itself permissions. Each installation's card on this screen says when that is the case. To add them:

  1. On GitHub, open the app's settings → Permissions & events. Under repository permissions set Checks and Commit statuses to Read-only. Under events subscribe to Check suite, Status and Pull request review. Save.
  2. Each account the app is installed on gets a request to accept the new permissions — from the installation's page (Change repositories on GitHub on its card). Once accepted, the card's note goes.

Until then, everything else works, and a status can be set by hand on any pull request.

Installing it ​

Press Install on repositories. On GitHub, pick the account, then either All repositories or Only select repositories. GitHub sends you back here, and the installation is listed with its repositories.

  • An app owned by an organisation is installed on that organisation. An app owned by your account can be installed only on your account.
  • If an organisation only lets owners install apps, your install becomes a request. It shows up here once an owner approves it.
  • To change which repositories it covers later, use Change repositories on GitHub. Crosdesk hears about the change by itself.

Refresh asks GitHub for the current list. Use it if something changed on GitHub and the screen hasn't caught up.

Shared repositories ​

Two workspaces can connect the same repository, each with its own app. GitHub tells both apps about every pull request there.

Because each workspace has its own TSK-12, a bare TSK-12 on a shared repository would be ambiguous. So on a shared repository, only the qualified form TSK-12@your-workspace links. A repository that another workspace also uses says so here. It shows how many other workspaces, but not which ones.

Recent deliveries ​

The last twenty events GitHub sent, and what became of each:

  • Done — processed.
  • Not needed — an event nothing here acts on.
  • Failed — with the reason.
  • Waiting — received, not yet processed.

If a pull request didn't link, look here first. If nothing arrived, GitHub couldn't reach Crosdesk; the app's Advanced page on GitHub lists each delivery and lets you resend it.

Removing the app ​

Remove makes Crosdesk forget the app and its installations, and stop linking. Links already made stay, showing the state GitHub last reported.

The app itself stays on GitHub. Delete it there, in the owner's Settings → Developer settings → GitHub Apps, so it stops sending events. After removing it, you can create a new one here.

Crosdesk · Buddhyantra LLP