Connecting GitHub

Pitwall reaches GitHub as a GitHub App you create for your instance. The app reads your repositories, opens pull requests, comments on them and merges the ones a person approved; it never pushes. Runners push, with their owner’s own git credentials.

Without the app Pitwall still starts: every repository shows as not reachable, and a run blocks at release, the step that opens the pull request.

Connecting it is done by hand, on GitHub and in the server’s settings. Pitwall has no screen for it yet.

Create the app

Once per instance.

1. On GitHub: Settings → Developer settings → GitHub Apps → New GitHub App. Give it a name and any homepage URL, and untick Webhook → Active: Pitwall polls.

2. Under Repository permissions, set these and nothing else:

   Permission	Access
   Contents	Read and write, to merge a pull request and delete its branch
   Pull requests	Read and write
   Checks	Read-only
   Commit statuses	Read-only
   Metadata	Read-only (GitHub sets it)

3. Under Where can this GitHub App be installed?, choose Any account if Pitwall will work on repositories of an organization besides your own account. An app limited to its account cannot be installed anywhere else.

4. Create the app, then Generate a private key. Set the server’s variables:

   Variable	Value
   PITWALL_GITHUB_APP_ID	The numeric App ID, not the client id
   PITWALL_GITHUB_APP_PRIVATE_KEY	The whole .pem file

   Set both or neither: with one alone the server refuses to start. The key may keep its line breaks or have each written as \n.

5. Install the app on each account whose repositories Pitwall works on, for all repositories or the ones you pick. On an organization, only an owner can install it.

6. Mount a volume for the mirror, below, and restart the server.

An app created before Contents was read and write needs the change made on the app, then accepted on each installation (Settings → Applications → Installed GitHub Apps → Configure). Until then a merge from Pitwall is refused and nothing else changes.

The mirror

The server keeps a read-only copy of each repository, a bare clone it fetches every minute. It renders documents, diffs and manual test scripts from it, and never writes to it.

The image keeps it in /var/lib/pitwall/mirror (PITWALL_MIRROR_DIR). Mount a named volume there: it takes the directory’s owner, the image’s user. A bind mount arrives owned by root and stops the server at start with “the mirror directory is not writable”.

The mirror is a cache. Deleting it loses nothing: the next fetch clones everything again. It is on only with both the directory and the app set.

A project’s repositories

Not in the UI yet

A project’s repositories are set through the API: PATCH /api/projects/{key} with {"repositories": ["owner/name"]}, the whole list. So are its build and test commands, build_command and test_command.

A repository that cannot be reached

A project’s page lists its repositories, and says why one cannot be reached:

It says	Do
GitHub is not configured	Set the app’s two variables and restart
The app is not installed	Install it on that account. The panel links to the install page
No such repository	Check the name. A private repository the app is not installed on reads the same: GitHub does not tell them apart
Rate limited, or unavailable	Wait: Pitwall reads again every minute

How fresh it is

Pitwall polls GitHub: what it shows is up to a minute old, fifteen seconds while CI runs. Webhooks are not used.