Deploy from a GitHub repository

Once a server is linked to a GitHub repository, the repository drives it. Every push to the default branch deploys, and every pull request into it gets a preview server of its own.

Before you start

• The server exists. Deploy it once with sokie deploy --create, or have its slug ready for --server.
• sokie.json is committed on the repository's default branch.
• The Sokie App is installed on the repository: github.com/apps/sokie-app. If it isn't, sokie link tells you, with the install link.

Link the repository

In the web app

On the server's Deploys tab, the card at the top says where deploys come from. Choose Link a repository there. (On the New server page, choose Link a GitHub repository before you create it, and the same dialog opens once the server exists.)

1. Connect GitHub. GitHub asks you to authorize the Sokie App as you, so Sokie can list the repositories you and the App can both see. If you've authorized it before, GitHub sends you straight back.
2. Repository. Each account the Sokie App is installed on has a tab, with a search. Each repository says what Sokie found there: a sokie.json, a spec, a link to another of your servers, or nothing. Not listed? Add an account or Choose which repositories it can see open GitHub; come back and the list refreshes.
3. Folder. Every folder on the default branch with a sokie.json is listed, so a monorepo with several servers works. The folder you pick is compared with what the server runs now, so you know whether the first deploy from git changes what agents see.
4. Linked. Sokie deploys the default branch's latest commit straight away, and the dialog follows that deploy.

If no folder has a sokie.json yet, download the server's files (or run sokie edit <slug>), commit and push them, then choose Check again.

Sokie keeps your GitHub sign-in only while the dialog is open, and for 15 minutes at most. It's sealed, never sent to your browser, and deleted when you link, close the dialog or run out of time. Sokie stores your GitHub login name with the link, never a token.

From a terminal

sokie link with no repository opens the same dialog in your browser, for the server this directory is linked to (or --server <slug>), and waits until you've linked:

$ sokie link
Opening GitHub, then the link dialog for petstore. If it doesn't open, go to:
  https://github.com/…
Pick the repository and folder there. Waiting for the link…
Linked your-org/petstore (main). Pushes to it now deploy.

If you know the repository, name it, and the dialog is skipped:

$ sokie link your-org/petstore
Opening GitHub to authorize the Sokie App. If it doesn't open, go to:
  https://github.com/…
Linked your-org/petstore (main). Pushes to it now deploy.

GitHub asks you to authorize the Sokie App once, so Sokie can check that you can see the repository. Sokie then deploys the default branch's latest commit straight away.

If sokie.json isn't at the repository's root, say where it is:

sokie link your-org/monorepo --path servers/petstore

Pushes deploy

Each push to the default branch deploys that commit, and gets a check named Sokie on GitHub. A deploy that goes live shows its tool count and address. A deploy that fails is titled with the reason, like MISSING_SECRETS, and the check's annotations put each finding on its file. Pushes to other branches don't deploy.

To change the server from now on, run sokie edit anywhere: it clones the repository (or finds your clone), opens your editor and starts sokie dev. See Edit a server in your editor.

You can still run sokie deploy from your machine. The CLI reminds you that the next push replaces whatever you deployed by hand.

Pull requests get previews

A pull request into the default branch gets its own server at:

https://pr-<number>--<slug>.sokie.cloud/mcp

Sokie comments on the pull request with the address and the tool count. It edits that one comment as you push, and the preview rebuilds on every push. When the pull request closes, merged or not, the preview is removed and the comment says so.

A preview is the same server under another address: it has the same access, the same secrets and the same connected clients, and it calls the same API as production. Try a change that writes data with that in mind.

Pull requests from forks are checked but never previewed, because a preview runs with the server's secrets.

See what GitHub did

Once linked, the card on the Deploys tab shows the repository, folder and branch, whether the Sokie App can see the repository, the last push and the deploy it made, the open previews, and who linked it. Below it, From GitHub lists each push and pull request of the last month with what it did: a deploy and whether it went live, a preview, "Fork: checked only", or "Ignored" for a push to another branch.

The card warns you in two cases:

• Sokie can't see the repository. The App was uninstalled or suspended, or the repository was taken out of its installation. Pushes stop deploying, and GitHub doesn't tell Sokie about them meanwhile; the server keeps running its last deploy. Give the App access again from the card, and the next push deploys. Pushes made while it was broken aren't deployed on their own, so push again (or run sokie deploy) if you need them live.
• Edits can't reach it yet. The App asks for permission to write branches, so edits saved in Sokie can open pull requests. Deploys and previews work without it; an owner of the account accepts it on GitHub, from the card's Review on GitHub.

Settings › Workspace › GitHub lists every account the App is installed on that your servers link through, with its state, and every linked server. Add an account installs the App on GitHub and brings you back there; the new account joins the list once a server links one of its repositories.

Change the folder

On the Deploys tab, choose Change folder. The dialog opens on the linked repository's folders, with the current one marked Linked here; pick another and choose Move and deploy. If the dialog's GitHub sign-in has ended, it asks you to connect again first. Choose Back to pick another repository instead.

From a terminal, link again: run sokie link to open the dialog and pick the folder, or name it with sokie link your-org/monorepo --path servers/billing. Either way the new link replaces the old one, and the old link's previews are taken down.

Unlink

On the Deploys tab, choose Unlink, or run:

$ sokie link --remove
Unlinked majestic-lobster-123 from GitHub. Pushes no longer deploy it.

The server keeps running its last deploy, at the same address. Pushes stop deploying, the open previews are taken down (their comments say so), and edits saved in Sokie stop opening pull requests. Nothing in the repository changes, and the Sokie App stays installed.

Linking another repository or folder in place of the current one takes the old link's previews down too.

Deploy from your own CI instead

If you'd rather your repository's own workflow deploy the server, without the Sokie App, use a deploy key and the sokie GitHub Action. A deploy key deploys one server and nothing else.

1. On the server's Overview, under Manage this server, in Deploy from CI, choose Make a deploy key. It's shown once: copy it.
2. Store it as a repository secret named SOKIE_DEPLOY_KEY (Settings › Secrets and variables › Actions, or gh secret set SOKIE_DEPLOY_KEY).
3. Add the action to a workflow:

on: [pull_request, push]
jobs:
  sokie:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: Abyssinia-Labs/sokie/packages/check-action@main
        with:
          deploy-key: ${{ secrets.SOKIE_DEPLOY_KEY }}

Pull requests are checked. A push to the default branch is checked and, when the check passes, deployed; the job summary gives the address and what the deploy found. Anywhere else, SOKIE_DEPLOY_KEY=… sokie deploy does the same.

Revoke a key on the server's page or in Settings › Connected clients, and its CI stops deploying at once.