Skip to content

Commit

Permalink
Deduplicate docs (#29)
Browse files Browse the repository at this point in the history 
Rust makes it easy to use external files in crate documentation, take
advantage of that to de-duplicate the README.md and the create level
documentation
  • Loading branch information
@sjoerdsimons
sjoerdsimons authored Feb 29, 2024
2 parents 8102e50 + 2a8e7eb commit 53cea91
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 147 deletions.
90 changes: 22 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,70 +1,24 @@
# gitlab-runner-rs

A crate to help build custom gitlab runner implementations.

## Implementing a custom runner

The overall idea is that this crate handles all interaction with the gitlab
server and drives the executions while the the runner implementation focus on
how to handle jobs from gitlab.

As the focus for an implementer of a custom runner is to implement the async
JobHandler trait, which gets calle during job executation. An absolute minimal
runner can be implement as such:

```rust,no_run
use gitlab_runner::{outputln, Runner, JobHandler, JobResult, Phase};
use std::path::PathBuf;
#[derive(Debug)]
struct Run {}
#[async_trait::async_trait]
impl JobHandler for Run {
async fn step(&mut self, script: &[String], phase: Phase) -> JobResult {
outputln!("Running script for phase {:?}", phase);
for s in script {
outputln!("Step: {}", s);
}
Ok(())
}
}
#[tokio::main]
async fn main() {
let mut runner = Runner::new(
"https://gitlab.example.com".try_into().unwrap(),
"runner token".to_owned(),
PathBuf::from("/tmp"));
runner.run(move | _job | async move { Ok(Run{}) }, 16).await.unwrap();
}
```

## Gitlab runner creation

This crate does not support creating new runners on the GitLab server. This can
be done using the
[runner creation API](https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user),
or manually in the GitLab
[runner management web interface](https://docs.gitlab.com/ee/ci/runners/runners_scope.html).
Make sure to follow the runner creation with an authentication token workflow,
as the registration token workflow is deprecated.

One key parameter provided when creating the runner is `run_untagged=false` (or
leaving the `Run untagged jobs` box unchecked in the web interface), which will
make the runner *only* pickup jobs which matches its tags. This is important to
prevent the runner from picking up "normal" jobs which it will not be able to
process.

When the runner is created GitLab provides an authentication token starting
with `glrt-`. This token should be provided to the runner for its GitLab
connection.

The token can be verified using a curl command like:

```shell
curl --request POST "https://GITLAB_URL/api/v4/runners/verify" \
--form "token=AUTHENTICATION_TOKEN"
```

This step is optional.
[![Crates.io][crates-badge]][crates-url]
[![Documentation][docs-badge]][docs-url]
[![MIT/Apache-2 licensed][license-badge]][license-url]
[![Build Status][actions-badge]][actions-url]

[crates-badge]: https://img.shields.io/crates/v/gitlab-runner
[crates-url]: https://crates.io/crates/gitlab-runner
[docs-badge]: https://docs.rs/gitlab-runner/badge.svg
[docs-url]: https://docs.rs/gitlab-runner
[license-badge]: https://img.shields.io/badge/license-MIT_OR_Apache--2-blue.svg
[license-url]: LICENSE-APACHE
[actions-badge]: https://github.com/collabora/gitlab-runner-rs/workflows/CI/badge.svg
[actions-url]:https://github.com/collabora/gitlab-runner-rs/actions?query=workflow%3ACI


[GitLab](https://gitlab.com) provides a REST style API for CI runners. These
crates abstract this API away so custom runners can easily be build without
any knowledge of the gitlab APIs

This workspace consists of two crates:
* [gitlab-runner](gitlab-runner/README.md) - Main runner crate
* gitlab-runner-mock - Mock crate for the gitlab runner APIs
84 changes: 84 additions & 0 deletions gitlab-runner/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# gitlab-runner-rs

A crate to help build custom gitlab runner implementations.

## Implementing a custom runner

The overall idea is that this crate handles all interaction with the gitlab
server and drives the executions while the the runner implementation focus on
how to handle jobs from gitlab.

As the focus for an implementer of a custom runner is to implement the async
JobHandler trait, which gets calle during job executation. An absolute minimal
runner can be implement as such:

```rust,no_run
use gitlab_runner::{outputln, GitlabLayer, RunnerBuilder, JobHandler, JobResult, Phase};
use tracing_subscriber::prelude::*;
use std::path::PathBuf;
#[derive(Debug)]
struct Run {}
#[async_trait::async_trait]
impl JobHandler for Run {
async fn step(&mut self, script: &[String], phase: Phase) -> JobResult {
outputln!("Running script for phase {:?}", phase);
for s in script {
outputln!("Step: {}", s);
}
Ok(())
}
}
#[tokio::main]
async fn main() {
let (layer, jobs) = GitlabLayer::new();
tracing_subscriber::Registry::default()
.with(
tracing_subscriber::fmt::Layer::new()
.pretty()
.with_filter(tracing::metadata::LevelFilter::INFO),
)
.with(layer)
.init();
let mut runner = RunnerBuilder::new(
"https://gitlab.example.com".try_into().expect("failed to parse url"),
"runner token",
"/tmp",
jobs
)
.build()
.await;
runner.run(move | _job | async move { Ok(Run{}) }, 16).await.unwrap();
}
```

## Gitlab runner creation

This crate does not support creating new runners on the GitLab server. This can
be done using the
[runner creation API](https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user),
or manually in the GitLab
[runner management web interface](https://docs.gitlab.com/ee/ci/runners/runners_scope.html).
Make sure to follow the runner creation with an authentication token workflow,
as the registration token workflow is deprecated.

One key parameter provided when creating the runner is `run_untagged=false` (or
leaving the `Run untagged jobs` box unchecked in the web interface), which will
make the runner *only* pickup jobs which matches its tags. This is important to
prevent the runner from picking up "normal" jobs which it will not be able to
process.

When the runner is created GitLab provides an authentication token starting
with `glrt-`. This token should be provided to the runner for its GitLab
connection.

The token can be verified using a curl command like:

```shell
curl --request POST "https://GITLAB_URL/api/v4/runners/verify" \
--form "token=AUTHENTICATION_TOKEN"
```

This step is optional.
80 changes: 1 addition & 79 deletions gitlab-runner/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,83 +1,5 @@
#![warn(missing_docs)]
//! A crate to help build custom gitlab runner implementations.
//!
//! ## Implementing a custom runner
//!
//! The overall idea is that this crate handles all interaction with the gitlab
//! server and drives the executions while the the runner implementation focus on
//! how to handle jobs from gitlab.
//!
//! As the focus for an implementer of a custom runner is to implement the async
//! JobHandler trait, which gets calle during job executation. An absolute minimal
//! runner can be implement as such:
//!
//! ```rust,no_run
//! use gitlab_runner::{outputln, GitlabLayer, RunnerBuilder, JobHandler, JobResult, Phase};
//! use tracing_subscriber::prelude::*;
//! use std::path::PathBuf;
//!
//! #[derive(Debug)]
//! struct Run {}
//!
//! #[async_trait::async_trait]
//! impl JobHandler for Run {
//! async fn step(&mut self, script: &[String], phase: Phase) -> JobResult {
//! outputln!("Running script for phase {:?}", phase);
//! for s in script {
//! outputln!("Step: {}", s);
//! }
//! Ok(())
//! }
//! }
//!
//! #[tokio::main]
//! async fn main() {
//! let (layer, jobs) = GitlabLayer::new();
//! tracing_subscriber::Registry::default()
//! .with(
//! tracing_subscriber::fmt::layer()
//! .pretty()
//! .with_filter(tracing::metadata::LevelFilter::INFO),
//! )
//! .with(layer)
//! .init();
//! let mut runner = RunnerBuilder::new(
//! "https://gitlab.example.com".try_into().expect("failed to parse url"),
//! "runner token",
//! "/tmp",
//! jobs
//! )
//! .build()
//! .await;
//! runner.run(move | _job | async move { Ok(Run{}) }, 16).await.unwrap();
//! }
//! ```
//!
//! ## Gitlab runner registration
//!
//! This crate does not support registering new runners with the gitlab server, so this has to be
//! done by hand using the gitlab
//! [runner registration API](https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner).
//!
//! The registration token can be retrieved from the runners section in the Gitlab
//! administration area. With that token the runner can be register using a curl
//! command like:
//! ```shell
//! curl --request POST "https://GITLAB_URL/api/v4/runners" \
//! --form "description=My custom runner" \
//! --form "run_untagged=false" \
//! --form "tag_list=custom-gitlab-runner" \
//! --form "token=REGISTRATION_TOKEN"
//! ```
//!
//! As a response to this command a new token for the registered runner will be
//! provided, this token should be provided to the runner for it's gitlab
//! connection.
//!
//! One thing to key parameter provided here is `run_untagged=false`, which will
//! make the runner *only* pickup jobs which matches its tag. This is important to
//! prevent the runner from picking up "normal" jobs which it will not be able to
//! process.
#![doc = include_str!("../README.md")]
pub mod artifact;
mod client;
mod logging;
Expand Down

0 comments on commit 53cea91

Please sign in to comment.