Skip to the content

DocumentationGitHub

Developer tools

GitHub

Issues, pull requests and deployments from GitHub

OpsCommand's GitHub App connects a handover to the code that fixes it:

  • an administrator or developer creates a GitHub issue from a handover, in one of its service's repositories;
  • they link an existing issue, pull request or commit by its address;
  • GitHub links a pull request or commit that mentions the handover (HO-12, in its title, body or message).

GitHub then tells OpsCommand when those items change: an issue closed or reopened, a pull request merged, a review approving or asking for changes. Each change shows on the handover and on the incident's timeline.

What the App may do. It reads and writes issues, and reads pull requests, commits and repository metadata. It never merges, pushes, deploys or reads secrets.

What an issue contains. An issue carries what a developer needs to start: the environment, the steps, the expected and actual behaviour, the error messages, the correlation IDs, the possible causes and where to look, already redacted. Logs, evidence and attachments stay in OpsCommand behind its permissions, and the issue links there.

Registering the App (the owner, once per OpsCommand installation)

  1. On GitHub, open Settings → Developer settings → GitHub Apps → New GitHub App, under the organisation that will own the App (for example FlyttGo Technologies Group's).
  2. Name: OpsCommand (or OpsCommand Staging for staging). The name becomes the slug in github.com/apps/<slug>.
  3. Homepage URL: the web address of OpsCommand.
  4. Setup URL (under Post installation): <APP_URL>/github/setup. Tick Redirect on update.
  5. Webhook: active. URL <API_URL>/v1/github/webhook. Secret: a new random value of at least 32 characters (it goes in GITHUB_WEBHOOK_SECRET and nowhere else).
  6. Repository permissions: Issues Read and write; Pull requests Read-only; Contents Read-only (to read commits); Metadata Read-only. Nothing else.
  7. Subscribe to events: Issues, Pull request, Pull request review, Push. Installation events come without asking.
  8. Where can this GitHub App be installed? Any account, so customers' organisations can install it. Choose Only on this account for staging.
  9. Note the App ID, and generate a private key (a .pem file).
  10. Give the API its settings as secrets in DeployPro (never in a repository or a chat):
  11. GITHUB_APP_ID: the App ID.
  12. GITHUB_APP_SLUG: the slug.
  13. GITHUB_APP_PRIVATE_KEY: the .pem's contents, or the file base64-encoded (base64 -w0 key.pem).
  14. GITHUB_WEBHOOK_SECRET: the webhook secret.
  15. Restart the API. Administration → Integrations now shows Install OpsCommand's GitHub App.

Connecting an organisation (its administrator)

  1. Administration → Integrations → Install OpsCommand's GitHub App. On GitHub, choose the account and the repositories.
  2. GitHub sends you back to OpsCommand. OpsCommand checks that the installation was started from this organisation by you, less than 30 minutes ago. It then asks GitHub whose installation it is and records it.
  3. On each service's page, under Repositories, name the repositories (owner/name) where its issues belong.

To disconnect, use Disconnect in OpsCommand, and uninstall the App on GitHub to stop its events. Uninstalling on GitHub alone is also recorded: OpsCommand takes nothing more from that installation.

The plan's acceptance: a real test repository (the owner)

This environment has no GitHub App of its own, so the code is proven against GitHub's documented example signature, webhook payloads shaped as GitHub sends them (apps/api/test/fixtures/github/) and a fake GitHub that checks the App's signed token (apps/api/test/github.test.ts). With the App registered for staging:

  1. Create a private repository, for example <your-org>/opscommand-test, and install the App on it.
  2. In OpsCommand staging, name it on a service. Create an incident and a handover, and send the handover to a developer.
  3. On the handover, Create GitHub issue. The issue appears on GitHub, linked back.
  4. Open a pull request whose description says Fixes HO-<n>. It appears on the handover.
  5. Approve it, then merge it. The handover shows Approved and Merged, and the incident's timeline has both.
  6. Close the issue. The handover shows it Closed.