add basic documentation for all plugins

[?]

Sep 29, 2021, 9:39 PM

C3XQSZZLH67TJDUA5HPWT445WJTWHZAIQTFUMA7PXTVT44LNGMNAC

Dependencies

[2] VIJBYUAV Add the project name to declarative inputs
[3] HBZEBIYZ Docs: document derivation attributes
[4] 3JXCTKEC Add markdown files for documentation
[5] JXFYZYDJ Add AuthenSASL to perl deps; improve email docs
[6] L4JYZ7BM doc: switch shell session code blocks to `console` type.

Change contents

edit in doc/manual/src/SUMMARY.md at line 8

[3.26]

[4.255]

- [Plugins](./plugins/README.md)
- [Declarative Projects](./plugins/declarative-projects.md)
file addition: plugins (d--r------)

[4.99]
file addition: README.md (----------)

[0.97]

# Plugins

This chapter describes all plugins present in Hydra.

### Inputs

Hydra supports the following inputs:

- Bazaar input
- Darcs input
- Git input
- Mercurial input
- Path input

## Bitbucket pull requests

Create jobs based on open bitbucket pull requests.

### Configuration options

- `bitbucket_authorization.<owner>`

## Bitbucket status

Sets Bitbucket CI status.

### Configuration options

- `enable_bitbucket_status`
- `bitbucket.username`
- `bitbucket.password`

## CircleCI Notification

Sets CircleCI status.

### Configuration options

- `circleci.[].jobs`
- `circleci.[].vcstype`
- `circleci.[].token`

## Compress build logs

Compresses build logs after a build with bzip2.

### Configuration options

- `compress_build_logs`

Enable log compression

### Example

```xml
compress_build_logs = 1
```

## Coverity Scan

Uploads source code to [coverity scan](https://scan.coverity.com).

### Configuration options

- `coverityscan.[].jobs`
- `coverityscan.[].project`
- `coverityscan.[].email`
- `coverityscan.[].token`
- `coverityscan.[].scanurl`

## Email notification

Sends email notification if build status changes.

### Configuration options

- `email_notification`

## Gitea status

Sets Gitea CI status

### Configuration options

- `gitea_authorization.<repo-owner>`

## GitHub pulls

Create jobs based on open GitHub pull requests

### Configuration options

- `github_authorization.<repo-owner>`

## Github refs

Hydra plugin for retrieving the list of references (branches or tags) from
GitHub following a certain naming scheme.

### Configuration options

- `github_endpoint`
- `github_authorization.<repo-owner>`

## Github status

Sets GitHub CI status.

### Configuration options

- `githubstatus.[].jobs`

Regular expression for jobs to match in the format `project:jobset:job`.
Defaults to `*:*:*`.

- `githubstatus.[].excludeBuildFromContext`

Don't include the build's ID in the status.

- `githubstatus.[].context`

Context shown in the status

- `githubstatus.[].useShortContext`

Renames `continuous-integration/hydra` to `ci/hydra` and removes the PR suffix
from the name. Useful to see the full path in GitHub for long job names.

- `githubstatus.[].description`

Description shown in the status. Defaults to `Hydra build #<build-id> of
<jobname>`

- `githubstatus.[].inputs`

The input which corresponds to the github repo/rev whose
status we want to report. Can be repeated.

- `githubstatus.[].authorization`

Verbatim contents of the Authorization header. See
[GitHub documentation](https://developer.github.com/v3/#authentication) for
details.

### Example

```xml
<githubstatus>
jobs = test:pr:build
inputs = src
authorization = Basic notgivingyoumypasswordosorry
excludeBuildFromContext = 1
</githubstatus>
```

## GitLab pulls

Create jobs based on open gitlab pull requests.

### Configuration options

- `gitlab_authorization.<projectId>`

## Gitlab status

Sets Gitlab CI status.

### Configuration options

- `gitlab_authorization.<projectId>`

## HipChat notification

Sends hipchat chat notifications when a build finish.

### Configuration options

- `hipchat.[].jobs`
- `hipchat.[].builds`
- `hipchat.[].token`
- `hipchat.[].notify`

## InfluxDB notification

Writes InfluxDB events when a builds finished.

### Configuration options

- `influxdb.url`
- `influxdb.db`

## Run command

Runs a shell command when the build is finished.

### Configuration options:

- `runcommand.[].job`

Regular expression for jobs to match in the format `project:jobset:job`.
Defaults to `*:*:*`.

- `runcommand.[].command`

Command to run. Can use the `$HYDRA_JSON` environment variable to access
information about the build.

### Example

```xml
<runcommand>
job = myProject:*:*
command = cat $HYDRA_JSON > /tmp/hydra-output
</runcommand>
```

## S3 backup

Upload nars and narinfos to S3 storage.

### Configuration options

- `s3backup.[].jobs`
- `s3backup.[].compression_type`
- `s3backup.[].name`
- `s3backup.[].prefix`

## Slack notification

Sending Slack notifications about build results.

### Configuration options

- `slack.[].jobs`
- `slack.[].force`
- `slack.[].url`

## SoTest

Scheduling hardware tests to SoTest controller

This plugin submits tests to a SoTest controller for all builds that contain
two products matching the subtypes "sotest-binaries" and "sotest-config".

Build products are declared by the file "nix-support/hydra-build-products"
relative to the root of a build, in the following format:

```
file sotest-binaries /nix/store/…/binaries.zip
file sotest-config /nix/store/…/config.yaml
```

### Configuration options

- `sotest.[].uri`

URL of the controller, defaults to `https://opensource.sotest.io`

- `sotest.[].authfile`

File containing `username:password`

- `sotest.[].priority`

Optional priority setting.

### Example

```xml
<sotest>
uri = https://sotest.example
authfile = /var/lib/hydra/sotest.auth
priority = 1
</sotest>
```
file addition: declarative-projects.md (----------)

[0.97]

## Declarative Projects

Hydra supports declaratively configuring a project\'s jobsets. This
configuration can be done statically, or generated by a build job.

> **Note**
>
> Hydra will treat the project\'s declarative input as a static definition
> if and only if the spec file contains a dictionary of dictionaries. If
> the value of any key in the spec is not a dictionary, it will treat the
> spec as a generated declarative spec.

### Static, Declarative Projects

Hydra supports declarative projects, where jobsets are configured from a
static JSON document in a repository.

To configure a static declarative project, take the following steps:

1. Create a Hydra-fetchable source like a Git repository or local path.

2. In that source, create a file called `spec.json`, and add the
specification for all of the jobsets. Each key is jobset and each
value is a jobset\'s specification. For example:

``` {.json}
{
"nixpkgs": {
"enabled": 1,
"hidden": false,
"description": "Nixpkgs",
"nixexprinput": "nixpkgs",
"nixexprpath": "pkgs/top-level/release.nix",
"checkinterval": 300,
"schedulingshares": 100,
"enableemail": false,
"emailoverride": "",
"keepnr": 3,
"inputs": {
"nixpkgs": {
"type": "git",
"value": "git://github.com/NixOS/nixpkgs.git master",
"emailresponsible": false
}
}
},
"nixos": {
"enabled": 1,
"hidden": false,
"description": "NixOS: Small Evaluation",
"nixexprinput": "nixpkgs",
"nixexprpath": "nixos/release-small.nix",
"checkinterval": 300,
"schedulingshares": 100,
"enableemail": false,
"emailoverride": "",
"keepnr": 3,
"inputs": {
"nixpkgs": {
"type": "git",
"value": "git://github.com/NixOS/nixpkgs.git master",
"emailresponsible": false
}
}
}
}
```

3. Create a new project, and set the project\'s declarative input type,
declarative input value, and declarative spec file to point to the
source and JSON file you created in step 2.

Hydra will create a special jobset named `.jobsets`. When the `.jobsets`
jobset is evaluated, this static specification will be used for
configuring the rest of the project\'s jobsets.

### Generated, Declarative Projects

Hydra also supports generated declarative projects, where jobsets are
configured automatically from specification files instead of being
managed through the UI. A jobset specification is a JSON object
containing the configuration of the jobset, for example:

``` {.json}
{
"enabled": 1,
"hidden": false,
"description": "js",
"nixexprinput": "src",
"nixexprpath": "release.nix",
"checkinterval": 300,
"schedulingshares": 100,
"enableemail": false,
"emailoverride": "",
"keepnr": 3,
"inputs": {
"src": { "type": "git", "value": "git://github.com/shlevy/declarative-hydra-example.git", "emailresponsible": false },
"nixpkgs": { "type": "git", "value": "git://github.com/NixOS/nixpkgs.git release-16.03", "emailresponsible": false }
}
}

```

To configure a declarative project, take the following steps:

1. Create a jobset repository in the normal way (e.g. a git repo with a
`release.nix` file, any other needed helper files, and taking any
kind of hydra input), but without adding it to the UI. The nix
expression of this repository should contain a single job, named
`jobsets`. The output of the `jobsets` job should be a JSON file
containing an object of jobset specifications. Each member of the
object will become a jobset of the project, configured by the
corresponding jobset specification.

2. In some hydra-fetchable source (potentially, but not necessarily,
the same repo you created in step 1), create a JSON file containing
a jobset specification that points to the jobset repository you
created in the first step, specifying any needed inputs
(e.g. nixpkgs) as necessary.

3. In the project creation/edit page, set declarative input type,
declarative input value, and declarative spec file to point to the
source and JSON file you created in step 2.

Hydra will create a special jobset named `.jobsets`, which whenever
evaluated will go through the steps above in reverse order:

1. Hydra will fetch the input specified by the declarative input type
and value.

2. Hydra will use the configuration given in the declarative spec file
as the jobset configuration for this evaluation. In addition to any
inputs specified in the spec file, hydra will also pass the
`declInput` argument corresponding to the input fetched in step 1 and
the `projectName` argument containing the project\'s name.

3. As normal, hydra will build the jobs specified in the jobset
repository, which in this case is the single `jobsets` job. When
that job completes, hydra will read the created jobset
specifications and create corresponding jobsets in the project,
disabling any jobsets that used to exist but are not present in the
current spec.
replacement in doc/manual/src/projects.md at line 310

[4.35737]→[4.35737:35758](∅→∅)

Declarative projects

[4.35737]

[4.35758]

Declarative Projects
edit in doc/manual/src/projects.md at line 312

[4.35779]→[4.35779:37797](∅→∅)

Hydra supports declaratively configuring a project\'s jobsets. This
configuration can be done statically, or generated by a build job.

> **Note**
>
> Hydra will treat the project\'s declarative input as a static definition
> if and only if the spec file contains a dictionary of dictionaries. If
> the value of any key in the spec is not a dictionary, it will treat the
> spec as a generated declarative spec.

### Static, Declarative Projects

Hydra supports declarative projects, where jobsets are configured from a
static JSON document in a repository.

To configure a static declarative project, take the following steps:

1. Create a Hydra-fetchable source like a Git repository or local path.

2. In that source, create a file called `spec.json`, and add the
specification for all of the jobsets. Each key is jobset and each
value is a jobset\'s specification. For example:

``` {.json}
{
"nixpkgs": {
"enabled": 1,
"hidden": false,
"description": "Nixpkgs",
"nixexprinput": "nixpkgs",
"nixexprpath": "pkgs/top-level/release.nix",
"checkinterval": 300,
"schedulingshares": 100,
"enableemail": false,
"emailoverride": "",
"keepnr": 3,
"inputs": {
"nixpkgs": {
"type": "git",
"value": "git://github.com/NixOS/nixpkgs.git master",
"emailresponsible": false
}
}
},
"nixos": {
"enabled": 1,
"hidden": false,
"description": "NixOS: Small Evaluation",
"nixexprinput": "nixpkgs",
"nixexprpath": "nixos/release-small.nix",
"checkinterval": 300,
"schedulingshares": 100,
"enableemail": false,
"emailoverride": "",
"keepnr": 3,
"inputs": {
"nixpkgs": {
"type": "git",
"value": "git://github.com/NixOS/nixpkgs.git master",
"emailresponsible": false
}
}
}
}
```
replacement in doc/manual/src/projects.md at line 313

[4.37798]→[4.37798:37990](∅→∅)

3. Create a new project, and set the project\'s declarative input type,
declarative input value, and declarative spec file to point to the
source and JSON file you created in step 2.

[4.37798]

[4.37990]

see this [chapter](./plugins/declarative-projects.md)
edit in doc/manual/src/projects.md at line 315

[4.37991]→[4.37991:40588](∅→∅),[4.40588]→[2.0:137](∅→∅),[2.137]→[4.40659:41012](∅→∅),[4.40659]→[4.40659:41012](∅→∅)

Hydra will create a special jobset named `.jobsets`. When the `.jobsets`
jobset is evaluated, this static specification will be used for
configuring the rest of the project\'s jobsets.

### Generated, Declarative Projects

Hydra also supports generated declarative projects, where jobsets are
configured automatically from specification files instead of being
managed through the UI. A jobset specification is a JSON object
containing the configuration of the jobset, for example:

``` {.json}
{
"enabled": 1,
"hidden": false,
"description": "js",
"nixexprinput": "src",
"nixexprpath": "release.nix",
"checkinterval": 300,
"schedulingshares": 100,
"enableemail": false,
"emailoverride": "",
"keepnr": 3,
"inputs": {
"src": { "type": "git", "value": "git://github.com/shlevy/declarative-hydra-example.git", "emailresponsible": false },
"nixpkgs": { "type": "git", "value": "git://github.com/NixOS/nixpkgs.git release-16.03", "emailresponsible": false }
}
}

```

To configure a declarative project, take the following steps:

1. Create a jobset repository in the normal way (e.g. a git repo with a
`release.nix` file, any other needed helper files, and taking any
kind of hydra input), but without adding it to the UI. The nix
expression of this repository should contain a single job, named
`jobsets`. The output of the `jobsets` job should be a JSON file
containing an object of jobset specifications. Each member of the
object will become a jobset of the project, configured by the
corresponding jobset specification.

2. In some hydra-fetchable source (potentially, but not necessarily,
the same repo you created in step 1), create a JSON file containing
a jobset specification that points to the jobset repository you
created in the first step, specifying any needed inputs
(e.g. nixpkgs) as necessary.

3. In the project creation/edit page, set declarative input type,
declarative input value, and declarative spec file to point to the
source and JSON file you created in step 2.

Hydra will create a special jobset named `.jobsets`, which whenever
evaluated will go through the steps above in reverse order:

1. Hydra will fetch the input specified by the declarative input type
and value.

2. Hydra will use the configuration given in the declarative spec file
as the jobset configuration for this evaluation. In addition to any
inputs specified in the spec file, hydra will also pass the
`declInput` argument corresponding to the input fetched in step 1 and
the `projectName` argument containing the project\'s name.

3. As normal, hydra will build the jobs specified in the jobset
repository, which in this case is the single `jobsets` job. When
that job completes, hydra will read the created jobset
specifications and create corresponding jobsets in the project,
disabling any jobsets that used to exist but are not present in the
current spec.