GitFOSS

# gitfoss-ci-runner

GitFOSS CI Runner is a crystal app that runs a GitFOSS CI pipeline stage  
from an input manifest file. Runs pipeline stages and exit with a status code.

It takes a manifest file as input and executes the pipeline stage(s) defined within.
It returns with an exit code of 0 or 1+, on success or failure respectively.
It has an endpoint that returns the pipeline stage status and logs.

## Installation

```
$ git clone https://github.com/gitfoss/gitfoss-ci-runner.git
$ cd gitfoss-ci-runner
$ shards build
$ cp ./bin/gitfoss-ci-runner /usr/bin/gitfoss-ci-runner
```

## Usage

Go to the [GitFOSS CI Runner register page] to get your registration nonce.  

```
$ gitfoss-ci-runner register --nonce=12345ABCDEF
# GitFOSS CI runner registered successfully.
# GitFOSS CI runner token: FEDCBA54321
```

After registration, return to the [GitFOSS CI Runner register page] to complete the registration. Input the runner token to associate it with your GitFOSS organization.  

That's it! Your runner is now registered and ready to run pipeline stages.  
Commit some code and push it to your GitFOSS repository to trigger a pipeline run.  

## Exposed API

The GitFOSS CI Runner exposes a simple HTTP API.  

### Pipeline

#### Trigger a stage run

```
POST /trigger

Headers:
  Authorization: Bearer $token
  Accept: application/json

Body:
  pipelineId: $pipelineId
  orgId: $orgId
  repoId: $repoId
  gitRepoDir: $gitRepoDir
  stageId: $stageId
```

This will return a JSON response with the pipeline run details.

```json
{
  "pipelineId": $pipelineId,
  "runId": $runId,
  "stageId": $stageId,
  "status": "PENDING" // PASSED, PENDING, RUNNING, SUCCESS, FAILURE, CANCELED
}
```

#### Reset/clear pipeline cache

Pass on `stage` to clear the cache for a specific pipeline stage.

```
POST /cache/reset

Headers:
  Authorization: Bearer $token
  Accept: application/json
```

This will clear the pipeline cache and respond with a 200 OK status.

### Pipeline Stages

#### Stage Status

```
GET /stage/$stageId

Headers:
  Authorization: Bearer $token
  Accept: application/json
```

This will return a JSON response with the pipeline stage status.

```json
{
  "pipelineId": $pipelineId,
  "stageId": $stageId,
  "status": "RUNNING" // PASSED, PENDING, RUNNING, SUCCESS, FAILURE, CANCELED
}
```

### Stage Logs

This endpoint has a special feature allowing to stream real-time logs from the pipeline stage.

Pass an optional query param `?stream=(http|ws|sse)` to stream logs via HTTP, WebSocket, or Server-Sent Events respectively.

```
GET /stage/$stageId/logs?stream=(http|ws|sse)

Headers:
  Authorization: Bearer $token
  Accept: application/json
```

This will return a JSON response with the pipeline run logs.

```json
{
  "pipelineId": $pipelineId,
  "stageId": $stageId,
  "logs": "... whatever the docker container logs are ..."
}
```

### Pipeline Artefacts

#### Artefact List

```
GET /run/$runId/artifacts

Headers:
  Authorization: Bearer $token
  Accept: application/json
```

This will return a JSON response with the pipeline run artefacts.

```json
{
  "pipelineId": $pipelineId,
  "runId": $runId,
  "stageId": $stageId,
  "artefacts": [
    {
      "id": $artefactId,
      "name": "filename.txt",
      "path": "/path/to/filename.txt",
      "size": 1024,
      "sha256": "sha256 hash of the file"
    }
  ]
}
```

### Runner Config

#### Get runner config

```
GET /runner/config

Headers:
  Authorization: Bearer $token
  Accept: application/json
```

This will return a JSON response with the runner configuration.

```json
{
  "registration": {
    "id": $runnerId,
    "url": "https://ci.gitfoss.dev/runners/$runnerId"
    "token": $runnerToken,
  },
  "defaultImage": "alpine:latest",
  "defaultTimeout": 900, // 15 minutes in seconds
  "successExit": [0], // exit codes that indicate success
}
```

### Runner version

```
GET /runner/version

Headers:
  Authorization: Bearer $token
  Accept: application/json
```

This will return a JSON response with the runner version.

```json
{
  "version": "0.1.0",
  "commit": "7ecdd3b"
}
```

## Development

TODO: Write development instructions here

## Contributing

1. Fork it (<https://gitfoss.dev/ethicdevs/gitfoss-ci-runner/fork>)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request

## Contributors

- [Willi Wonka](https://gitfoss.dev/@willi.wonka38) - creator and maintainer

## License

This project is released under the [MIT License](LICENSE).