Skip to main content
Who this is for. Operators running Ewake in their own AWS account (BYOC). If you’re using Ewake’s hosted service, connect the shared App from the main GitHub integration page instead.
A self-hosted deployment reads GitHub as a GitHub App you own. You create the App, you hold its private key, and the install callback completes on your own deployment — nothing routes through Ewake. This is the only way to connect GitHub here. There is no token form in the dashboard and no token field in the integration: reads are made with installation tokens, minted on demand and never stored. A deployment that does not read GitHub can skip this page entirely.
The App path installs from github.com and reads api.github.com, which covers GitHub Enterprise Cloud as well. A self-hosted GitHub Enterprise Server is a different host and this flow does not reach it — talk to us before you start.

Why an App

An App is installed on the organisation by an owner, is granted a fixed set of permissions, and keeps working when that person leaves. Its tokens are minted per installation, live about an hour, and are never written down — so there is nothing to rotate, nothing to leak from the database, and no one person’s rate limit shared across every read. That is the reason there is no token option to fall back to.

Register it from the dashboard

The quickest route, and the one that keeps the private key away from whoever runs Terraform.
1

Open the GitHub tile

You need the Root role on the deployment: the first person from your company domain to sign in has it. In Integrations, click the GitHub tile under Add more. Enter your organisation login in GitHub organization — the name that appears in your repository URLs — and click Create the Ewake GitHub app.
2

Review the App on GitHub

The dashboard sends you to GitHub with a prepared manifest. GitHub shows you what the App will be called and what it asks for before you agree to anything:Ewake writes only to branches named ewake/… and to the pull requests it opens from them. See Pull requests from ewake.The public inbound URL is public_inbound_base_url when you set it, the gateway’s URL when public_inbound_gateway is on with a private load balancer (alb_internal = true), and the dashboard URL otherwise. GitHub has to reach it for ewake to follow its pull requests and to run GitHub Actions flows. Without it the App still reads. The gateway routes /api/v1/github/events, with the Slack, alert and deployment paths.
3

Create it

GitHub creates the App and sends your browser back to the deployment with a one-time code. The deployment exchanges that code for the App’s credentials and writes them to ewake/<tenant_name>/<company.name>/github-app in your own AWS account. Then it sends you straight on to install the App.
The App exists and the deployment holds its key. No Terraform, no apply, no restart — the dashboard reads the secret on its next request.
GitHub also returns a client secret during this exchange. Ewake does not read or store it: nothing uses it, and keeping it would widen what a leak of that secret would cost you. Ewake stores the webhook secret, which it checks every webhook delivery against.
Start this from the dashboard, not from GitHub. The dashboard sets a session-scoped nonce before it sends you over, and the callback refuses a request that arrives without one.

Or seed it from Terraform

Use this when you already have an App you want the deployment to act as, rather than creating a new one. Take these values off the App’s settings page: Then set the first three in terraform.tfvars and apply. If the App has a webhook, also set github_app_webhook_secret, so the deployment can check each delivery:
A .tfvars file takes literal values only. file("your-app.private-key.pem") looks natural there and is rejected outright:
Paste the PEM as the heredoc above, or keep it in its own file and pass it through the environment, where cat is available:
Don’t try to answer Terraform’s interactive prompt with it — that reads one line, and a PEM is many.
All three or none. Setting one or two fails the plan, naming which are missing. That case is almost always a half-finished edit. github_app_webhook_secret is optional, and the plan refuses it without the other three.github_app_private_key and github_app_webhook_secret are declared sensitive, so Terraform keeps them out of plan output and the apply log. They still reach the state file — that is what passing a key to Terraform costs. The state backend wants encryption and restricted reads, and whoever runs the apply can read the key. Registering from the dashboard avoids both.
If you create the App by hand rather than from the manifest, set its Setup URL to <your-dashboard-url>/api/v1/auth/github/callback and tick Redirect on update. GitHub calls Setup URL optional; Ewake requires it. Leave it blank and the install finishes on GitHub’s own page with no callback ever reaching your deployment. Give the App the permissions in the table above. For the webhook, set its URL to <your public inbound URL>/api/v1/github/events, set a webhook secret, and subscribe to the four events in that table.

Install it

From the dashboard route, GitHub sends you to the install page as soon as the App is created. From the Terraform route, the App is registered but not yet installed: go to Integrations, click the GitHub tile under Add more, then Install the Ewake GitHub app.
Install it on the organisation, not on your user account. Ewake reads an organisation, and the callback refuses a personal installation.

Troubleshooting

After clicking Install, GitHub lands you on the App’s settings page. Setup URL is empty on the App. Open the App on GitHub → Post installation → set Setup URL to <your-dashboard-url>/api/v1/auth/github/callback → Save changes. Then uninstall the App from your organisation and reinstall from the Ewake dashboard. You changed the installation on GitHub and landed on “Could not connect GitHub. Please try again.” Expected, and harmless. Redirect on update sends you back to Ewake after any change to the installation, but a change you started on GitHub carries none of the session state the callback checks, so the callback refuses it. Your change is already saved on GitHub, and Ewake picks up the new repositories on its next installation token — within the hour. Registering from the dashboard ends on “Could not register the GitHub App with the code GitHub returned.” (?error=github_app_manifest_failed). The one-time code GitHub returns is good for an hour and is spent on the first exchange, so this is not retryable by reloading. Check the dashboard’s logs: Rejected a GitHub App manifest callback that carried no connect nonce of ours means the flow was not started from the GitHub tile in Integrations in this browser session. Start again from there. If an App was created on GitHub before the failure, delete it first: GitHub App names are unique, so a second Ewake (<your company name>) cannot be created while the first exists. Integrations reports missing GitHub App permissions. GitHub applies the manifest only when it creates the App, so an App created before Ewake asked for a permission keeps its old set. Ewake names each permission it lacks. Add them on the App’s settings page on GitHub (Permissions & events), then have an organisation owner approve the updated permissions on the installation. The dashboard reports “Could not connect GitHub. Please try again.” after install. Check its logs. Two common causes:
  • Rejected a GitHub callback that carried no connect nonce of ours — the install was started from the App’s page on GitHub rather than from the Ewake dashboard. The dashboard sets a session-scoped nonce before it sends you to GitHub, and the callback checks it. Uninstall and start again from the GitHub tile in the dashboard’s Integrations page.
  • GitHub App identity: private key parse failed — the PEM in your deployment’s github-app secret has been collapsed onto one line, or its newlines were not escaped as \n inside the JSON string. This only happens to a hand-written secret; one the dashboard wrote is always correct. Build it with a tool rather than by hand:
    --rawfile is what preserves the newlines. Check it round-trips with ... | jq -r '.APP_PRIVATE_KEY' | openssl rsa -noout -check.

Rotating the key

Generate a new private key on the App’s settings page, then update the secret — point github_app_private_key at the new PEM and apply, or write the new value to ewake/<tenant_name>/<company.name>/github-app directly if the App was registered from the dashboard. Either way the running task keeps the old key: the deployment caches the App identity once it has found one, so force a new deployment of the dashboard service to pick up the new key. Delete the old key on GitHub once the new one is serving. The App, its installation and its slug are unchanged, so nothing else moves.