Skip to Content
How-to guidesUse your own GitHub App

Use your own GitHub App

Run GitHub on an app your org owns. Members sign in through your app, repository events from it start your deputies and runs, and you hold the keys. Everything your team already connected keeps working. With the App’s ID and private key, Marshal also reads your pull requests across the organization for Impact.

Before you start

  • Role: admin or owner in Marshal. In GitHub, you need permission to create an App in your GitHub organization.
  • Available when your administrator enables webhooks.
  • Marshal shows the URLs you paste into the App on the GitHub row under OAuth apps and on the Webhooks page. Keep both open.

Steps

Create the App on GitHub from Marshal

The fastest path: Marshal fills in the App for you and nothing is copied back.

  1. In Marshal, open the organization menu in the top bar and choose Organization settings, then OAuth apps.
  2. Find the GitHub row, select Own app in the connect mode toggle, and find Create on GitHub at the top of the Own app panel.
  3. Choose A GitHub organization and enter its name in GitHub organization, or choose My personal account.
  4. Keep Private: only the account that owns it can install it, or choose Public: any GitHub account can install it. Private is the default. A public App lets other GitHub accounts install it. Marshal only uses installations it verified for your organization, so an installation by anyone else is never used.
  5. Select Create on GitHub. GitHub opens with the App filled in, with the callback and setup URLs, the permissions and the events. Confirm it there.
  6. GitHub sends you back to Marshal. The panel shows the App verified, with its Client ID, App slug and private key saved. Marshal stores the secrets encrypted and never shows them again.
  7. Select Enable, then continue with Turn on event delivery. For an App created this way, Enable delivery sets the webhook URL and secret on GitHub for you, so there is nothing to paste.

When your Marshal has no public address for GitHub to send you back to, the panel says so and you enter the App’s details by hand instead. Prefer to build the App yourself? Follow the manual steps below.

Create the GitHub App by hand

  1. In GitHub, open your organization Settings > Developer settings > GitHub Apps and select New GitHub App.

  2. Set the Callback URL to the Redirect URI that Marshal shows on the GitHub row under OAuth apps, with Own app selected. Turn on Expire user authorization tokens.

  3. Set the Setup URL to https://<your-marshal-host>/api/auth/callback/github-install and turn on Redirect on update.

  4. Under Repository permissions, set:

    PermissionAccess
    ContentsRead and write
    IssuesRead and write
    Pull requestsRead and write
    MetadataRead-only

  5. Under Subscribe to events, tick push, pull_request, pull_request_review, issues, issue_comment and sub_issues.

  6. Leave Webhook for the next section. Create the App, then generate a client secret on its page. Note the Client ID, the client secret and the app slug, which is the last part of https://github.com/apps/<slug>.

  7. Note the App ID, the number at the top of the App’s settings page, and under Private keys select Generate a private key. GitHub downloads a .pem file.

Give Marshal the app (hand-built App)

  1. In Marshal, open the organization menu in the top bar and choose Organization settings, then OAuth apps.
  2. Find the GitHub row and select Own app in the connect mode toggle. Until your app is in use, the mode reads Own app Set up (or Own app Manage once you saved one), and selecting it opens the Own app panel.
  3. In the Own app panel, enter the Client ID, the Client secret and the App slug. Enter the App ID and the Private key too: paste the PEM or drop the .pem file. The App ID and key let Marshal read pull requests across your organization, so Impact shows your repos’ history and resolves every pull request your agents touch. Select Save. Marshal checks the pair with GitHub, stores the secret and the key encrypted, and never shows them again.
  4. Select Test connection. GitHub opens for a real sign-in, then brings you back to Marshal with the app verified.
  5. Select Enable.

Turn on event delivery

  1. Open Organization settings, then Webhooks, and stay on the Receivers tab.
  2. On the GitHub card, select Enable delivery.
  3. Marshal shows Copy these now with the Webhook URL, the Webhook secret and the Setup URL. In your GitHub App settings, turn on Webhook, tick Active, then paste the URL and the secret. Save the App. Marshal shows the secret once, so copy it before you select Done.

Install the App

  1. On the GitHub card on Settings > Webhooks, choose Your own GitHub App and select Install on GitHub.
  2. If GitHub asks you to sign in, approve access. GitHub then opens its install page.
  3. Choose the account and repositories, then install. GitHub sends you back to Marshal, and Marshal links the installation itself.
  4. The card changes to Active.

Members connect GitHub

Members connect from Connections with Sign in with GitHub, and the consent screen shows your app. Connections made before you switched keep working, and new sign-ins use your app.

What you should see

  • The Own app panel shows Enabled, and Private key shows Key set.
  • The GitHub card shows Active.
  • After a push or a pull request in an installed repository, Last event shows its time. Events arrive up to 10 MiB.
  • Events carry the same names as before, such as push and pull_request.opened, so your missions keep matching them.

Replace the private key

In the Own app panel, select Rotate, then Replace next to the key. Enter the App ID and the new Private key, then select Save. Marshal checks the pair with GitHub before it stores it, and a key that does not belong to the App ID changes nothing.

Rotate the webhook secret

On the GitHub card, select Rotate secret. Choose Keep old secret for 24 hours to give yourself a day to paste the new secret into your GitHub App, or End old secret now. Marshal shows the new secret once. The Webhook URL stays the same.

Switch back to Marshal’s app

On the GitHub row, choose Marshal app in the toggle. New sign-ins use Marshal’s app, and everyone who is already connected keeps working. Select Disable in the panel when you want your app to stop sending events to Marshal. Remove delivery on the GitHub card ends the webhook URL.

If you disable your own app while Own app is chosen, GitHub stays on Own app and connecting pauses until you enable the app again or choose another mode.

Next

Run a mission on a schedule or event: start a deputy from a pull request.

Use your own Slack appCreate a webhook endpoint