~sircmpwn/sr.ht-docs

588f191a0cec756f069eb9fbcaa2b630cc77897b — Ben Burwell 8 months ago 38ae770
Document SSH access to builds.sr.ht
2 files changed, 32 insertions(+), 0 deletions(-)

A builds.sr.ht/build-ssh.md
M builds.sr.ht/manifest.md
A builds.sr.ht/build-ssh.md => builds.sr.ht/build-ssh.md +23 -0
@@ 0,0 1,23 @@
---
title: SSH access to build VMs
---

You can interact directly with your builds by connecting to the runner over SSH.
This is helpful for troubleshooting your manifests, or just getting a quick
temporary environment to test something in.

When a build fails, the VM stays alive for an extra ten minutes, and you'll be
presented with instructions on how to connect to the runner via SSH, e.g.:

```
$ ssh -t builds@azusa.runners.sr.ht connect 81809
Connected to build job #81809 (failed):
https://builds.sr.ht/jobs/~sircmpwn/81809
Your VM will be terminated 4 hours from now, or when you log out.

bash-5.0 $
```

In addition to connecting to failed builds over SSH, you can add `shell: true`
to your [manifest](manifest.md) to always enable SSH access. Then, you'll be
able to interact with your build as it runs.

M builds.sr.ht/manifest.md => builds.sr.ht/manifest.md +9 -0
@@ 57,6 57,15 @@ A list of extra repositories to enable with the image's package manager. The
specific format varies by base image, [consult the compatibility
page](/builds.sr.ht/compatibility.md) for details.

## shell

*boolean*

Whether to keep the build VM alive after all of the tasks have finished, even if
it doesn't fail, so you can SSH in. You can also SSH in before the tasks have
finished and tail the output of the build in your terminal. [Learn more about
SSH access to build VMs](build-ssh.md).

## sources

*list* (of *string*)