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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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
  • creator and maintainer

License

This project is released under the MIT License.