~sircmpwn/sr.ht-docs

7e055f2dd5256f0083ac446022ccc8328a5ad873 — Stephen Gregoratto 2 years ago d70774e
Use fenced code blocks where applicable.
M builds.sr.ht/api.md => builds.sr.ht/api.md +45 -41
@@ 14,35 14,37 @@ specified scope.

Inserts a new job into the job queue.

    {
      "manifest": "string",         The build manifest
      "note": "string",             Human-friendly description of this build
                                      (markdown, optional)
      "tags": [...],                Arbitrary list of strings that identify this
                                      build and can be used to navigate the
                                      dashboard. Each string must use only
                                      lowercase alphanumeric characters, or any
                                      of "-_.:" (optional)
      "access:read": [              List of users that have read access to this
                                      job (optional). The user submitting the
                                      build will be included regardless of this
                                      value. The special username "*" indicates
                                      public read access to this build.
                                      Defaults to *.
        "string"                    Username
      ],
      "access:write": [             List of users that have write access to this
                                      job (optional). The user submitting the
                                      build will be included regardless of this
                                      value.
        "string"                    Username
      ],
      "triggers": [...],            Post-build triggers (optional)
      "execute": boolean,           True to start the build immediately
                                      (optional - defaults to true)
      "secrets": boolean,           True to provide secrets during the build
                                      (optional - defaults to true)
    }
```
{
  "manifest": "string",         The build manifest
  "note": "string",             Human-friendly description of this build
                                  (markdown, optional)
  "tags": [...],                Arbitrary list of strings that identify this
                                  build and can be used to navigate the
                                  dashboard. Each string must use only
                                  lowercase alphanumeric characters, or any
                                  of "-_.:" (optional)
  "access:read": [              List of users that have read access to this
                                  job (optional). The user submitting the
                                  build will be included regardless of this
                                  value. The special username "*" indicates
                                  public read access to this build.
                                  Defaults to *.
    "string"                    Username
  ],
  "access:write": [             List of users that have write access to this
                                  job (optional). The user submitting the
                                  build will be included regardless of this
                                  value.
    "string"                    Username
  ],
  "triggers": [...],            Post-build triggers (optional)
  "execute": boolean,           True to start the build immediately
                                  (optional - defaults to true)
  "secrets": boolean,           True to provide secrets during the build
                                  (optional - defaults to true)
}
```

See also: [Build triggers](triggers.md)



@@ 52,19 54,21 @@ Gets information about a job by its ID.

**Scopes**: jobs:read

```
{
  "id": integer,
  "status": "job status enum",
  "setup_log": "url",               URL to captured stdout/stderr of setup
  "tasks": [
    {
      "id": integer,
      "status": "job status enum",
      "setup_log": "url",               URL to captured stdout/stderr of setup
      "tasks": [
        {
          "name": "setup",
          "status": "task status enum"
          "log": "url",
        },
        ...
      ]
    }
      "name": "setup",
      "status": "task status enum"
      "log": "url",
    },
    ...
  ]
}
```

### Job status enum


M builds.sr.ht/index.md => builds.sr.ht/index.md +39 -33
@@ 27,12 27,14 @@ Build manifests are YAML files that contain a description of your build
environment and steps to run in that environment. A very simple example could
be:

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

When you submit this build, we'll fire up a virtual machine running an
up-to-date image of Alpine Linux. Then, we'll copy your scripts into the machine


@@ 40,29 42,31 @@ and run them one at a time. More complex build jobs will probably use more
features of the build.yml - here's an example that deploys
[web.synapse-bt.org](https://web.synapse-bt.org):

    image: archlinux
    packages:
      - nodejs
      - npm
      - rsync
    sources:
      - https://git.sr.ht/~sircmpwn/receptor
    environment:
      deploy: synapse@synapse-bt.org
    secrets:
      - 7ebab768-e5e4-4c9d-ba57-ec41a72c5665
    tasks:
      - setup: |
          cd receptor
          npm install
      - build: |
          cd receptor
          npm run build:production
      - deploy: |
          cd receptor
          sshopts="ssh -o StrictHostKeyChecking=no"
          rsync --rsh="$sshopts" -rP index.html $deploy:/var/www/web.synapse-bt.org/
          rsync --rsh="$sshopts" -rP dist $deploy:/var/www/web.synapse-bt.org/
```yaml
image: archlinux
packages:
  - nodejs
  - npm
  - rsync
sources:
  - https://git.sr.ht/~sircmpwn/receptor
environment:
  deploy: synapse@synapse-bt.org
secrets:
  - 7ebab768-e5e4-4c9d-ba57-ec41a72c5665
tasks:
  - setup: |
      cd receptor
      npm install
  - build: |
      cd receptor
      npm run build:production
  - deploy: |
      cd receptor
      sshopts="ssh -o StrictHostKeyChecking=no"
      rsync --rsh="$sshopts" -rP index.html $deploy:/var/www/web.synapse-bt.org/
      rsync --rsh="$sshopts" -rP dist $deploy:/var/www/web.synapse-bt.org/
```

A [full reference](manifest.md) for build manifests is available.



@@ 82,10 86,12 @@ OAuth key which has access to the secrets specified in the build manifest.

Each task's script is given a preamble that looks like this:

    #!/usr/bin/env bash
    . ~/.buildenv
    set -x
    set -e
```sh
#!/usr/bin/env bash
. ~/.buildenv
set -x
set -e
```

The actual shell varies depending on your build image. `~/.buildenv` contains
the environment variables you specified in your manifest, but feel free to

M builds.sr.ht/manifest.md => builds.sr.ht/manifest.md +7 -5
@@ 65,10 65,12 @@ user in the build environment.
A list of scripts to execute in the build environment. These scripts are run
with the following preamble:

    #!/usr/bin/env bash
    . ~/.buildenv
    set -x
    set -e
```sh
#!/usr/bin/env bash
. ~/.buildenv
set -x
set -e
```

~/.buildenv contains environment variables specified by the `environment`
directive.


@@ 94,7 96,7 @@ See also: [Build triggers](triggers.md)
*dictionary* (of *string: string* OR *string: list*)

A list of key/value pairs for options to set in the build environment via
~/.buildenv.
`~/.buildenv`.

## secrets


M builds.sr.ht/triggers.md => builds.sr.ht/triggers.md +13 -9
@@ 1,18 1,22 @@
At the end of a job or a job group, you can execute triggers based on the
outcome of the job. The basic format is (in JSON):

    {
        "action": "trigger type",
        "condition": "when to execute this trigger",
        [...action-specific configuration...]
    }
```
{
    "action": "trigger type",
    "condition": "when to execute this trigger",
    [...action-specific configuration...]
}
```

Or in YAML:

    triggers:
      - action: trigger type
        condition: when to execute this trigger
        ...action-specific configuration...
```
triggers:
  - action: trigger type
    condition: when to execute this trigger
    ...action-specific configuration...
```

Condition may be one of the following:


M git.sr.ht/installation.md => git.sr.ht/installation.md +29 -25
@@ 20,8 20,10 @@ It is necessary to configure git.sr.ht's SSH dispatcher as the system-wide SSH
authorization hook. In `/etc/ssh/sshd_config`, configure git-srht-dispatch like
so:

    AuthorizedKeysCommand=/usr/bin/git-srht-dispatch "%u" "%h" "%t" "%k"
    AuthorizedKeysCommandUser=root
```
AuthorizedKeysCommand=/usr/bin/git-srht-dispatch "%u" "%h" "%t" "%k"
AuthorizedKeysCommandUser=root
```

sshd will invoke our dispatcher whenever a connection is made to the server to
obtain a list of authorized keys for the connecting user. The default behavior


@@ 47,29 49,31 @@ favorite cron daemon. We recommend the following crontab:
git.sr.ht does not do this for you - you need to wire it up in nginx. Here's an
example config:

    location = /authorize {
        proxy_pass http://127.0.0.1:5001;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI $request_uri;
    }

    location ~ ^.*/objects/([0-9a-f]+/[0-9a-f]+|pack/pack-[0-9a-f]+.(pack|idx)).*$ {
        auth_request /authorize;
        root /var/lib/git;
    }

    location ~ ^.*/(HEAD|info/refs|objects/info/.*|git-(upload|receive)-pack).*$ {
        auth_request /authorize;
        root /var/lib/git;
        fastcgi_pass unix:/run/fcgiwrap.sock;
        fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
        fastcgi_param PATH_INFO $uri;
        fastcgi_param GIT_PROJECT_ROOT $document_root;
        fastcgi_param GIT_HTTP_EXPORT_ALL "";
        include fastcgi_params;
        gzip off;
    }
```nginx
location = /authorize {
    proxy_pass http://127.0.0.1:5001;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

location ~ ^.*/objects/([0-9a-f]+/[0-9a-f]+|pack/pack-[0-9a-f]+.(pack|idx)).*$ {
    auth_request /authorize;
    root /var/lib/git;
}

location ~ ^.*/(HEAD|info/refs|objects/info/.*|git-(upload|receive)-pack).*$ {
    auth_request /authorize;
    root /var/lib/git;
    fastcgi_pass unix:/run/fcgiwrap.sock;
    fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
    fastcgi_param PATH_INFO $uri;
    fastcgi_param GIT_PROJECT_ROOT $document_root;
    fastcgi_param GIT_HTTP_EXPORT_ALL "";
    include fastcgi_params;
    gzip off;
}
```

It's important that you set up the `/authorize` endpoint to enforce the privacy
of private repositories.

M tutorials/getting-started-with-builds.md => tutorials/getting-started-with-builds.md +4 -4
@@ 12,7 12,7 @@ which can be submitted to builds.sr.ht for processing.

Let's start with a basic manifest:

```yml
```yaml
image: alpine/edge
tasks:
- example: |


@@ 43,7 43,7 @@ see "hello world" shown under the "example" task.
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
```yaml
image: alpine/edge
sources:
- https://git.sr.ht/~sircmpwn/scdoc


@@ 66,7 66,7 @@ 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
```yaml
image: alpine/edge
packages:
- meson


@@ 94,7 94,7 @@ images use different package managers.
Portability is important - so let's try running the same manifest on another
operating system.

```yml
```yaml
image: freebsd
packages:
- meson