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.
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.
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:
<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.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’sgithub-appsecret has been collapsed onto one line, or its newlines were not escaped as\ninside 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:--rawfileis 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 — pointgithub_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.