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 read set, 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.

​
1. Create the App

Go to https://github.com/organizations/<your-org>/settings/apps/new (replace <your-org> with your organisation’s login — the one that appears in your repository URLs). Fill in these fields — leave everything else at its default:
GitHub labels Setup URL as optional on the form; that is optional to GitHub — Ewake requires it. It is the URL GitHub redirects to once someone installs the App, so a blank Setup URL leaves the customer on the App’s own settings page on GitHub, and the install completes with no callback ever reaching Ewake.
Redirect on update is the checkbox directly under Setup URL. Tick it. Without it, someone who already has the App installed and clicks Install in the Ewake dashboard again — to add a repository, say — saves the change on GitHub and is then left sitting there, while the dashboard waits on a callback that never arrives.
Then grant the read permissions Ewake calls:
  • Repository permissions (all Read): Contents, Issues, Pull requests, Actions, Deployments. Metadata is set to Read automatically.
  • Organization permissions (Read): Members.
Click Create GitHub App.
A few things worth knowing before you do:
  • The organisation must be an organisation, not a personal account. An App on a personal account installs only on that person, and Ewake’s install callback refuses that.
  • The dashboard URL under Setup URL must be https://. GitHub will not call back over plain http, and the path /api/v1/auth/github/callback must match exactly.
  • App names are unique across GitHub. Ewake (<your-org>) avoids collisions with other customers. The slug follows the name — GitHub lowercases it and replaces spaces with hyphens — so Ewake (acme) becomes ewake-acme. Note the slug: you need it in step 3.

​
2. Collect three values

Creating the App lands you on its settings page. From here:
The App also shows a CLIENT_SECRET. Ewake does not use it — the OAuth user-to-server flow it exists for is not part of this integration. Leave it out.

​
3. Hand them to terraform

The three are terraform variables on your deployment — github_app_client_id, github_app_slug and github_app_private_key. Apply, and terraform creates the Secrets Manager secret holding them and injects GITHUB_CLIENT_ID, GITHUB_APP_SLUG and GITHUB_APP_PRIVATE_KEY into the reactive task. Nothing to create by hand. github_app_private_key is declared sensitive, so terraform keeps it out of plan output and the apply log. It still reaches the state file — that is what passing a key to terraform costs — so the state backend wants encryption and restricted reads, as it already does for the JWT and admin passwords terraform generates for you. The self-hosted repository declares all three for you, so put them in your terraform.tfvars:
A .tfvars file takes literal values only. file("your-app.private-key.pem") looks natural there and is rejected outright:
Paste the PEM in 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 only one or two fails the plan, naming which are missing. That case is almost always a half-finished edit.Leaving all three unset is a supported deployment, but it means GitHub is not connected at all — there is no token form to fall back to. The dashboard says the deployment has no App configured, and that is the whole story.
Setting the three on an older application build is harmless — terraform writes the secret and injects the values, and a build that does not read them ignores them. The install action appears once you are on a build that does. Check the release notes.

​
4. Install it

From the dashboard, not from GitHub: Integrations → GitHub → Install the Ewake GitHub App.
Starting from the App’s own page on GitHub skips the step that ties the install to your browser session, and the callback refuses it.

​
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 “GitHub connection failed”. 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. Start the change from Integrations → GitHub in the dashboard to skip the detour. The dashboard reports “GitHub connection failed” after install. Check reactive’s 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 Integrations → GitHub in the dashboard.
  • 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. Re-seed the secret with the PEM’s real newlines encoded as \n.

​
Rotating the key

Generate a new private key on the App’s settings page, point github_app_private_key at the new PEM, and apply — terraform writes a new version of the secret. The ARN does not change, so the task definition does not either and the running task keeps the old key in memory: force a new deployment of the reactive service to pick it up. 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.