# Integrating builds.sr.ht with GitHub

This is an adaptation of our [getting started with
builds.sr.ht](../getting-started with builds.sr.ht) tutorial, but for code
hosted on GitHub.

## Build manifests

Unlike platforms like Jenkins, builds.sr.ht does not allow you to pre-configure
jobs. And unlike platforms like Travis, jobs are not inherently tied to a git
repository. Each job on builds.sr.ht is described ad-hoc with a build manifest,
which can be submitted to builds.sr.ht for processing.

Let's start with a basic manifest:

```yaml
image: alpine/edge
tasks:
- example: |
    echo "hello world"
```

This is a build manifest, written in [YAML](http://yaml.org/). When we submit
this to builds.sr.ht, it will boot up an [Alpine
Linux](https://alpinelinux.org/) virtual machine using the edge release of
Alpine Linux. Then it will execute each of our build tasks - in this case,
saying "hello world".

## Submitting jobs on the web

builds.sr.ht has a web submission form, where you can paste a build manifest and
submit the job without any additional configuration. This is a useful way of
testing build manifests before giving them a permanent home, or running one-off
tasks. Visit the [job submission form](https://builds.sr.ht/submit) and paste in
the example manifest. Add a note, perhaps "my first job", and click "submit" to
run the job.

You'll be redirected to the job detail page. In a moment, one of our job runners
will pick up the task and start processing it. Within a few seconds, you should
see "hello world" shown under the "example" task.

## Adding git repositories to builds

Let's try building [mrsh](https://github.com/emersion/mrsh), which depends on
[meson](https://mesonbuild.com/). Here's a build manifest for it:

```yaml
image: alpine/edge
packages:
- meson
sources:
- https://github.com/emersion/mrsh
tasks:
- configure: |
    cd mrsh
    meson build
- build: |
    cd mrsh
    ninja -C build
- test: |
    cd mrsh
    ninja -C build test
```

Before starting your tasks, builds.sr.ht will clone each repository listed in
"sources" to the build environment. You can have as many or as few (including
zero) git repositories as you like. builds.sr.ht will also install [Alpine
Linux's meson package][meson] before starting your build. This uses Alpine's
native `apk` package manager - other images use different package managers.

[meson]: https://pkgs.alpinelinux.org/package/edge/main/x86_64/meson

## Testing on other platforms

Portability is important - so let's try running the same manifest on another
operating system.

```yaml
image: freebsd
packages:
- meson
sources:
- https://github.com/emersion/mrsh
tasks:
- configure: |
    cd mrsh
    meson build
- build: |
    cd mrsh
    ninja -C build
- test: |
    cd mrsh
    ninja -C build test
```

This one happens to work without any changes, but note that some images have
different names for packages, different distributions of coreutils, and so on.

## Adding these builds to your GitHub repository

Try making a new "mrsh" repository on your GitHub account. Note that forks won't
work - so make sure you make a *new* repository and push the mrsh code to it.
Take a look at the `.builds` directory in mrsh: each of these build manifests
can be submitted on push or pull request by rigging up a dispatch.sr.ht task.

Go to [dispatch.sr.ht](https://dispatch.sr.ht) and "Configure new task". Pick
"GitHub commits > builds.sr.ht jobs" and click "Add task" for your new mrsh
repository. That's all you have to do! Now let's make a dummy commit and push it
to GitHub to test it out:

    git commit --allow-empty -m "Testing builds.sr.ht"
    git push

Head over to your [builds.sr.ht dashboard](https://builds.sr.ht) and you should
see your build begin momentarily!

## Testing pull requests on GitHub

If you want to run your CI against pull requests on GitHub, follow a similar
procedure, but select "GitHub pull requests > builds.sr.ht jobs" instead. Then,
each new pull request that comes into your repo will be built on builds.sr.ht
and the pull request status updated with the build results.

## Why doesn't my GitHub repo show up?

There are a couple of limitations:

- Forks are not supported
- You must have admin access to the repo (test this by trying to add a webhook
  through the GitHub UI manually)

If neither of these are the issue, [write us an email](mailto:sir@cmpwn.com).

---

<div class="alert alert-info">
  <strong>Want to learn more about builds.sr.ht?</strong>
  Check out all of our <a href="builds.sr.ht">builds.sr.ht tutorials</a>.
</div>

Other resources:

- [builds.sr.ht user manual](/builds.sr.ht)
- [Build manifest reference](/builds.sr.ht/manifest.md)
- [dispatch.sr.ht](/dispatch.sr.ht)