diff options
Diffstat (limited to 'tutorials')
| -rw-r--r-- | tutorials/builds.sr.ht/github-integration.md | 145 | ||||
| -rw-r--r-- | tutorials/builds.sr.ht/index.html | 81 | ||||
| -rw-r--r-- | tutorials/getting-started-with-builds.md | 5 |
3 files changed, 231 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> diff --git a/tutorials/getting-started-with-builds.md b/tutorials/getting-started-with-builds.md index 2604e4b..c8d5489 100644 --- a/tutorials/getting-started-with-builds.md +++ b/tutorials/getting-started-with-builds.md @@ -124,6 +124,11 @@ manifests at `.builds/*.yml`. --- +<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) |