diff --git a/docs/integrations/gitlab-runner.md b/docs/integrations/gitlab-runner.md new file mode 100644 index 0000000..0b3e19e --- /dev/null +++ b/docs/integrations/gitlab-runner.md @@ -0,0 +1,49 @@ +# GitLab Runner Executor + +It is possible to run GitLab jobs in isolated ephemeral Tart Virtual Machines via [Tart Executor](https://github.com/cirruslabs/gitlab-tart-executor). +Tart Executor utilizes [custom executor](https://docs.gitlab.com/runner/executors/custom.html) feature of GitLab Runner. + +# Basic Configuration + +Configuring Tart Executor for GitLab Runner is as simple as installing `gitlab-tart-executor` binary from Homebrew: + +```bash +brew install cirruslabs/cli/gitlab-tart-executor +``` + +And updating configuration of your self-hosted GitLab Runner to use `gitlab-tart-executor` binary: + +```toml +concurrent = 2 + +[[runners]] + # ... + executor = "custom" + builds_dir = "/Users/admin/builds" # directory inside the + cache_dir = "/Users/admin/cache" + [runners.feature_flags] + FF_RESOLVE_FULL_TLS_CHAIN = false + [runners.custom] + prepare_exec = "gitlab-tart-executor" + prepare_args = ["prepare"] + run_exec = "gitlab-tart-executor" + run_args = ["run"] + cleanup_exec = "gitlab-tart-executor" + cleanup_args = ["cleanup"] +``` + +Now you can use Tart Images in your `.gitlab-ci.yml`: + +```yaml +# You can use any remote Tart Image. +# Tart Executor will pull it from the registry and use it for creating ephemeral VMs. +image: ghcr.io/cirruslabs/macos-ventura-base:latest + +test: + tags: + - tart-installed # in case you tagged runners with Tart Executor installed + script: + - uname -a +``` + +For more advanced configuration please refer to [GitLab Tart Executor repository](https://github.com/cirruslabs/gitlab-tart-executor). diff --git a/mkdocs.yml b/mkdocs.yml index 3b45845..81eaf0e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,6 +87,7 @@ nav: - "Quick Start": quick-start.md - "Integrations": - "GitHub Actions": integrations/github-actions.md + - "GitLab Runner": integrations/gitlab-runner.md - "Self-hosted CI": integrations/cirrus-cli.md - "Managing VMs": integrations/vm-management.md - "Licensing": licensing.md