From 739296b556d60974c6e750f57fbcb671872ec6a5 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Sun, 3 Mar 2019 15:00:09 -0700 Subject: Add Github -> builds.sr.ht tutorial --- tutorials/builds.sr.ht/github-integration.md | 145 +++++++++++++++++++++++++++ tutorials/builds.sr.ht/index.html | 81 +++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 tutorials/builds.sr.ht/github-integration.md create mode 100644 tutorials/builds.sr.ht/index.html (limited to 'tutorials/builds.sr.ht') 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). + +--- + +
+ Want to learn more about builds.sr.ht? + Check out all of our builds.sr.ht tutorials. +
+ +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 @@ +

+ Ready to do more with builds.sr.ht? Here is a collection of useful tutorials + for setting up various kinds of build automations. +

+ +
+
+

Getting started with builds.sr.ht

+

+ Running your first few jobs on our continuous integration platform, + builds.sr.ht. +

+ + Read more + + + + +
+
+
+

Using builds.sr.ht for GitHub CI

+

+ builds.sr.ht can be used to run CI for platforms outside of sourcehut - + here's how. +

+ + Read more + + + + +
+ +
+
+ More tutorials are coming! + Is there something in particular you want to see here? Mention it on + sr.ht-discuss! +
-- cgit