3 files changed, 287 insertions, 0 deletions
diff --git a/tutorials/getting-started-with-builds.md b/tutorials/getting-started-with-builds.md
new file mode 100644
index 0000000..7a0b29e
--- /dev/null
+++ b/tutorials/getting-started-with-builds.md
@@ -0,0 +1,131 @@
+# Getting started with builds.sr.ht
+
+builds.sr.ht is our build automation platform. We're going to walk through the
+process of running jobs on builds.sr.ht and a look at few useful features.
+
+## 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:
+
+```yml
+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 a new build manifest. This one is going to compile and test the
+[scdoc](https://git.sr.ht/~sircmpwn/scdoc) project.
+
+```yml
+image: alpine/edge
+sources:
+- https://git.sr.ht/~sircmpwn/scdoc
+tasks:
+- build: |
+    cd scdoc
+    make
+- test: |
+    cd scdoc
+    make check
+```
+
+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.
+
+## Adding dependencies
+
+scdoc is a simple project with no dependencies. Let's try a slightly more
+complex one: [mrsh](https://git.sr.ht/~emersion/mrsh), which depends on
+[meson](https://mesonbuild.com/). Here's a build manifest for it:
+
+```yml
+image: alpine/edge
+packages:
+- meson
+sources:
+- https://git.sr.ht/~emersion/mrsh
+tasks:
+- configure: |
+    cd mrsh
+    meson build
+- build: |
+    cd mrsh
+    ninja -C build
+- test: |
+    cd mrsh
+    ninja -C build test
+```
+
+This time, builds.sr.ht will install [Alpine Linux's meson
+package](https://pkgs.alpinelinux.org/package/edge/main/x86_64/meson) before
+starting your build. This uses Alpine's native `apk` package manager - other
+images use different package managers.
+
+## Testing on other platforms
+
+Portability is important - so let's try running the same manifest on another
+operating system.
+
+```yml
+image: freebsd
+packages:
+- meson
+sources:
+- https://git.sr.ht/~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 git repository
+
+If you put a build manifest in `.build.yml` at the top of your repo, a build job
+will be created each time you push new commits. You can also create multiple
+manifests, for example to test multiple platforms, by putting several build
+manifests at `.builds/*.yml`.
+
+---
+
+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/index.html b/tutorials/index.html
new file mode 100644
index 0000000..5175c8f
--- /dev/null
+++ b/tutorials/index.html
@@ -0,0 +1,80 @@
+<p>
+  <strong>Welcome to sr.ht!</strong> We have lots of helpful tutorials to
+  introduce you to our platform and get you productive as soon as possible.
+</p>
+<style>
+.tutorial:not(:last-child) {
+  margin-bottom: 1rem;
+}
+</style>
+<div class="event-list">
+  <div class="event" style="margin-left: -0.5rem; margin-right: -0.5rem;">
+    <h3>Setting up your account &amp; first git repository</h3>
+    <p>
+      This tutorial is recommended as the first stop for any new user.
+    </p>
+    <a href="set-up-account-and-git.md" class="btn btn-success">
+      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>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 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/set-up-account-and-git.md b/tutorials/set-up-account-and-git.md
new file mode 100644
index 0000000..7d4b531
--- /dev/null
+++ b/tutorials/set-up-account-and-git.md
@@ -0,0 +1,76 @@
+If this is your first time using git, we recommend starting with the [Git
+Book](https://git-scm.com/book/en/v2). It's free, translated into many
+languages, and easy to read. Read at least the first 3 chapters.
+
+# Setting up your account & first git repository
+
+Thanks for signing up for sr.ht! Let's start by setting up your profile details.
+Your profile page is on meta.sr.ht, the sr.ht account management service. You
+can fill in some basic (and optional) details like your bio on your [profile
+page](https://meta.sr.ht/profile). Before we can get any work done, however, we
+need to set up your SSH key and add it on the keys page.
+
+## Generating an SSH key
+
+sr.ht does not support pushing to git repositories over HTTPS with a
+username+password - SSH keys are mandatory. If you already have an SSH key, you
+can skip this step. If not, run the following command to generate one:
+
+    ssh-keygen
+
+If you accept the defaults, the public key will be written to
+`~/.ssh/id_rsa.pub` and the private key to `~/.ssh/id_rsa`.
+
+## Uploading your key to meta.sr.ht
+
+The meta.sr.ht [keys page](https://meta.sr.ht/keys) has a form for adding your
+SSH key. If you followed the earlier instructions to generate an SSH key, your
+public key is stored at `~/.ssh/id_rsa.pub`. Copy the contents of this file to
+your clipboard and paste it into the text field. Click "Add key" and your key
+will now be valid for pushing to git repositories.
+
+## Creating a git repository
+
+If you already have a git repository you want to push to git.sr.ht, you can skip
+this step. If not, open up a shell and run the following commands to create a
+test repository for experimenting with:
+
+    mkdir example
+    cd example
+    git init
+    echo "Hello world!" >README.md
+    git add README.md
+    git commit -m "Initial commit"
+
+This created a new git repository and added a `README.md` file to it, then
+created the initial commit.
+
+## Pushing your repository to git.sr.ht
+
+The following commands will add a "remote" to your local git repository, which
+will allow you to push changes to a remote repository on git.sr.ht.
+
+    git remote add origin git@git.sr.ht:~username/example
+
+Make sure to replace `username` with your own. Then this command will push your
+master branch to git.sr.ht:
+
+    git push -u origin master
+
+Since this repository didn't previously exist, you'll be prompted with a link to
+create the repository on git.sr.ht - click that link and fill out the form on
+that page. You'll be redirected to your repository on git.sr.ht: you're done!
+
+<div class="alert alert-primary">
+    <strong>Tip</strong>: You can create repositories on the web on the
+    git.sr.ht <a href="https://git.sr.ht/create">new repository page</a>.
+</div>
+
+---
+
+Next: [Getting started with builds.sr.ht](getting-started-with-builds.md)
+
+Other resources:
+
+- [The git book](https://git-scm.com/book/en/v2)
+- [git.sr.ht user manual](/git.sr.ht)