GitHub

Keep a copy of each connection's shared layer in your own GitHub repository, as one pull request that Kater keeps up to date.

Audience

Platform admins

Prerequisites

The settings permission in Kater (settings:manage)
Admin rights on the GitHub repository
The Kater CLI, signed in with kater login

Write-back keeps a copy of your shared layer in your own GitHub repository, where your team can review it and run CI on it. Kater keeps one pull request open into your default branch, and you merge it when you want. Write-back is optional and one-way: Kater never reads anything back from GitHub.

What write-back does

It does	It does not
Write each connection’s `modeling/` folder, the source datasets and the shared layer, to one folder of your repository	Write workspaces, apps or anyone’s Personal folder
Keep one pull request open from the `kater/shared` branch into your default branch	Merge the pull request. You merge it
Replace the folder with what Kater holds, on top of the latest default branch	Read changes back from GitHub. The next write-back undoes them
Use Kater’s GitHub App, on the repositories you select	Use a person’s GitHub account

For each run, Kater asks GitHub for a token on the one repository, with these permissions:

Permission	What Kater uses it for
Contents: write	Write the folder to the `kater/shared` branch
Pull requests: write	Open the pull request and keep it up to date
Metadata: read	Find the repository and its default branch

Before you start

The repository needs one commit. Kater builds on the latest commit of the default branch. In a new, empty repository, commit a README first.
Use a folder that holds only Kater’s files. Each write-back replaces the whole folder, so Kater removes any other file in it from the pull request.

Connect a repository

Start in a terminal.

Run kater admin write-back connect. It opens GitHub in your browser.
Terminal window
```
kater admin write-back connect
```
Authorize Kater.

GitHub asks you to authorize Kater’s GitHub App as yourself. Select Authorize. The page then says “Signed in to GitHub as” and your GitHub name. Go back to your terminal.
Select the account.

At “Which GitHub account?”, select the organisation or the user that owns the repository. When Kater’s App is not on that account yet, select Install Kater’s GitHub App on another account. GitHub opens. Select the account, select Only select repositories, select your repository, then select Install. In your terminal, answer yes at “Installed?”.
Select the repository.

“Which repository?” lists the repositories where you have admin rights.
Name the folder.

At “Folder in the repository for Kater’s shared layer”, press ↵ for kater/, or type a folder such as analytics/kater/.
Select when Kater writes back.

Select After each publish, or On a cron schedule (UTC). A cron schedule then asks for the expression. The default, 0 6 * * *, writes back at 06:00 UTC each day.

The terminal then says where Kater writes, for example: “Kater writes its shared layer to kater/ in acme/analytics, after each publish, and keeps one pull request from kater/shared into main open.”

To connect a different repository, run kater admin write-back connect again. The new repository replaces the old one.

The pull request

Connecting does not write back at once. With After each publish, Kater writes back about a minute after a change to the shared layer is published, from the portal, an agent or kater git push. To write back now, run kater admin write-back run.

Each write-back makes one commit, “Kater shared layer at” and the Kater version it holds, and moves the kater/shared branch to it. The pull request, “Kater: shared layer”, shows what changed since your default branch. Each connection’s files are in <folder>connections/<connection>/modeling/.

Make changes in Kater

Kater moves the kater/shared branch to its own commit each time. A commit you push to that branch, or a change you make in the pull request, is lost at the next write-back. Make changes in Kater.

When your default branch already holds exactly what Kater holds, a write-back changes nothing and opens no pull request.

Check write-back

Run kater admin write-back status.

kater admin write-back status

Line	What it says
The first line	The repository, the folder, the branch and the schedule
`Last run:`	When Kater last wrote back, or `never`
`Pull request:`	The number of the open pull request
`[last run failed]`	Why the last write-back failed
`[problem]`	Why Kater’s GitHub App cannot reach the repository now. When it can, the line says “Kater’s GitHub App reaches it.”

Stop writing back

Run kater admin write-back disconnect. Kater stops writing back and forgets the repository. What is already in GitHub stays. To remove Kater’s App from the repository too, uninstall it in your GitHub settings.

kater admin write-back disconnect

If something does not work

What you see	What to do
“You need admin rights on” a repository “to connect it.”	Ask an admin of the repository to connect it, or to give you admin rights.
“The folder must be a relative path such as `kater/` or `analytics/kater/`.”	Type the folder without a `/` at the start.
“This link has expired” in the browser	Run `kater admin write-back connect` again.
“This command opens GitHub in your browser; run it in a terminal.”	Run it in a terminal, not in a script or an agent.
`[last run failed]` and “has no commits on” a branch “to build on”	Commit a README to the default branch, then run `kater admin write-back run`.
“This Kater server has no GitHub App configured.”	Write-back is not on for your organisation yet. Contact Kater.