Add Github -> builds.sr.ht tutorial

2 files changed, 226 insertions, 0 deletions

diff --git a/tutorials/builds.sr.ht/github-integration.md b/tutorials/builds.sr.ht/github-integration.md
new file mode 100644
index 0000000..21f9ea7
--- /dev/null
+++ b/tutorials/builds.sr.ht/github-integration.md
@@ -0,0 +1,145 @@
+# 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 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)
diff --git a/tutorials/builds.sr.ht/index.html b/tutorials/builds.sr.ht/index.html
new file mode 100644
index 0000000..13b1513
--- /dev/null
+++ b/tutorials/builds.sr.ht/index.html
@@ -0,0 +1,81 @@
+<p>
+  Ready to do more with builds.sr.ht? Here is a collection of useful tutorials
+  for setting up various kinds of build automations.
+</p>
+<style>
+.tutorial:not(:last-child) {
+  margin-bottom: 1rem;
+}
+</style>
+<div class="tutorial">
+  <div class="event" style="margin-left: -0.5rem; margin-right: -0.5rem;">
+    <h3 id="getting-started-with-buildssrht">Getting started with builds.sr.ht</h3>
+    <p>
+      Running your first few jobs on our continuous integration platform,
+      builds.sr.ht.
+    </p>
+    <a href="../getting-started-with-builds.md" class="btn btn-default">
+      Read more
+      <span class="icon icon-caret-right">
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
+      </span>
+    </a>
+  </div>
+</div>
+<div class="tutorial">
+  <h3>Using builds.sr.ht for GitHub CI</h3>
+  <p>
+    builds.sr.ht can be used to run CI for platforms outside of sourcehut -
+    here's how.
+  </p>
+  <a href="github-integration.md" class="btn btn-default">
+    Read more
+    <span class="icon icon-caret-right">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
+    </span>
+  </a>
+</div>
+<!--
+<div class="tutorial">
+  <h3>Contributing to projects on sr.ht</h3>
+  <p>
+    How to configure git to send emails and sending your first patches.
+  </p>
+  <a href="contributing-to-projects.md" class="btn btn-default">
+    Read more
+    <span class="icon icon-caret-right">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
+    </span>
+  </a>
+</div>
+<div class="tutorial">
+  <h3>Accepting patches from a mailing list</h3>
+  <p>
+    Integrating patches from mailing lists into your own projects.
+  </p>
+  <a href="accepting-patches-from-lists.md" class="btn btn-default">
+    Read more
+    <span class="icon icon-caret-right">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
+    </span>
+  </a>
+</div>
+<div class="tutorial">
+  <h3>Using secrets on builds.sr.ht</h3>
+  <p>
+    How to securely use secret data in builds.sr.ht jobs.
+  </p>
+  <a href="using-secrets-in-builds.md" class="btn btn-default">
+    Read more
+    <span class="icon icon-caret-right">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg>
+    </span>
+  </a>
+</div>
+-->
+<hr />
+<div class="alert alert-primary">
+  <strong>More tutorials are coming!</strong>
+  Is there something in particular you want to see here? Mention it on
+  <a href="https://lists.sr.ht/~sircmpwn/sr.ht-discuss">sr.ht-discuss</a>!
+</div>