From 0a738ecab68b0e5cb523baaa35470665a92613cf Mon Sep 17 00:00:00 2001 From: Rin Oliver Date: Mon, 5 Jan 2026 15:14:16 -0600 Subject: [PATCH] docs: update links to point to new page[s], reformat for clarity --- GitLab/README.md | 8 ++-- GitLab/custom-executor.md | 12 +++--- GitLab/runner-manual-setup.md | 72 ++++++++++++++++++++++++----------- GitLab/shell-executor.md | 12 +++--- GitLab/template-config.md | 2 +- 5 files changed, 66 insertions(+), 40 deletions(-) diff --git a/GitLab/README.md b/GitLab/README.md index 2e38841..c4cd115 100644 --- a/GitLab/README.md +++ b/GitLab/README.md @@ -1,6 +1,6 @@ -# Orka-GitLab Integration +# Orka GitLab Integration -The Orka-GitLab integration provides guides on how to use [Orka by MacStadium][orka] in a GitLab CI/CD pipeline. -You can find guide on how to use [GitLab Shell executor](shell-executor.md) and [GitLab Custom executor](custom-executor.md). +The Orka GitLab integration enables you to use [Orka by MacStadium][orka] in your GitLab CI/CI pipelines. +Learn how to configure the [GitLab Shell executor](shell-executor.md) or the [GitLab Custom executor](custom-executor.md). -[orka]: https://www.macstadium.com/orka \ No newline at end of file +[orka]: https://www.macstadium.com/orka diff --git a/GitLab/custom-executor.md b/GitLab/custom-executor.md index 8b957f6..6c5ce22 100644 --- a/GitLab/custom-executor.md +++ b/GitLab/custom-executor.md @@ -86,14 +86,12 @@ This means your Orka environment must have visibility to the GitLab server. Visibility from the GitLab server to the Orka environment is not required. [custom]: https://docs.gitlab.com/runner/executors/custom.html -[orka]: https://orkadocs.macstadium.com/docs/getting-started -[cli]: https://orkadocs.macstadium.com/docs/example-cli-workflows -[api]: https://documenter.getpostman.com/view/6574930/S1ETRGzt?version=latest -[quick-start]: https://orkadocs.macstadium.com/docs/quick-start +[orka]: https://support.macstadium.com/hc/en-us/articles/29904434271387-Orka-Overview +[cli]: https://support.macstadium.com/hc/en-us/articles/42514244203419-Orka3-CLI-Overview-Configuration +[api]: https://macstadium.github.io/orka-api-docs/ +[quick-start]: https://support.macstadium.com/hc/en-us/articles/28347375974555-Orka3-CLI-Quick-Start [docker]: https://www.docker.com/ [obtain-token]: https://docs.gitlab.com/ee/ci/runners/#registering-a-specific-runner-with-a-project-registration-token [register-runner]: https://docs.gitlab.com/runner/register/index.html -[custom-config-page]: https://docs.gitlab.com/runner/executors/custom.html -[config-page]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html [env-variables]: https://docs.gitlab.com/ee/ci/variables/ -[ip-plan]: https://orkadocs.macstadium.com/docs/orka-glossary#section-ip-plan +[ip-plan]: https://support.macstadium.com/hc/en-us/articles/28230867289883-IP-Plan diff --git a/GitLab/runner-manual-setup.md b/GitLab/runner-manual-setup.md index 61bda87..2bd5bb0 100644 --- a/GitLab/runner-manual-setup.md +++ b/GitLab/runner-manual-setup.md @@ -1,38 +1,66 @@ # Set up a GitLab Runner manually -This guide explains how to set up a GitLab Runner manually. If you want to set it up automatically, using a Docker container, see [here](custom-executor.md#set-up-a-gitlab-runner). +This guide walks through manual GitLab Runner setup. For automated setup using Docker, see the [Custom executor guide](custom-executor.md#set-up-a-gitlab-runner). -## Requirements +## Prerequisites -- GitLab [Runner][runner] -- [jq][jq] - command-line JSON processor used by the provided scripts +Before you begin, ensure you have the following: -## Set up a GitLab Runner +- GitLab [Runner][runner] access and installation privileges +- [jq][jq] (command-line JSON processor) - required by the integration scripts +- An Orka base image with SSH key configured +- Administrative access to the machine where the Runner will be installed -To set up a GitLab Runner manually, you need to: +## Setup steps -1. Install the Runner. You can install a GitLab Runner one of three ways: [manually][manual-install], via a [homebrew installation][homebrew-install], or in a Docker [container][docker-install]. -2. [Obtain a token][obtain-token]. The token will be used in **Step 3** to register the newly installed GitLab Runner. -3. [Register][register-runner] the Runner. This is the process that binds the Runner to GitLab. -**Note**: When asked to enter the executor type, select `custom`. -4. Copy the provided scripts to the Runner machine: [base.sh](scripts/base.sh), [prepare.sh](scripts/prepare.sh), [run.sh](scripts/run.sh), [cleanup.sh](scripts/cleanup.sh). -**Note**: All scripts should be in the same directory. For example you can add them to `/var/custom-runner`. -5. Verify the scripts can be executed by running `chmod +x path_to_script` in the command line. -6. Update the Runner config file: - * Verify the `builds_dir` and `cache_dir` settings are present. - **Note**: Both the `builds_dir` and `cache_dir` paths must be present on the Orka VM, which will execute the build. - * Verify the `[runners.custom]` section is available and the `prepare_exec`, `run_exec` and `cleanup_exec` are set to point to the `prepare.sh`, `run.sh` and `cleanup.sh` scripts. +### 1. Install GitLab Runner - **Note**: A template config file is available [here](template-config.md). - For information about the location of the file and its contents, see the GitLab Runner [configuration page][config-page] and the Custom executor [configuration page][custom-config-page]. -7. Verify [jq][jq] is installed. For more information, see [jq][jq] page. -8. Verify that the private SSH key for connecting to the ephemeral VM is present on the Runner machine under this path `/root/.ssh/id_rsa`. This key was created earlier during the Orka base image setup. +Install the Runner using one of these methods: + +- [Manual installation][manual-install] (binary) +- [Homebrew installation][homebrew-install] (macOS) +- [Docker container][docker-install] + +### 2. Obtain a registration token + +Follow GitLab's instructions to [obtain a registration token][obtain-token] for your project or group. You'll use this token in the next step. + +### 3. Register the Runner + +[Register the Runner][register-runner] with GitLab. When prompted for the executor type, select **custom**. + +### 4. Configure the integration scripts + +1. Copy these scripts to the Runner machine: [base.sh](scripts/base.sh), [prepare.sh](scripts/prepare.sh), [run.sh](scripts/run.sh), [cleanup.sh](scripts/cleanup.sh) +2. Place all scripts in the same directory (e.g., `/var/custom-runner`) +3. Make the scripts executable: `chmod +x /var/custom-runner/*.sh` + +### 5. Configure the Runner + +Edit the Runner configuration file to include: + +- **Build and cache directories**: Set `builds_dir` and `cache_dir` paths that exist on your Orka VMs +- **Custom executor settings**: Configure the `[runners.custom]` section with paths to your scripts: + - `prepare_exec` → `prepare.sh` + - `run_exec` → `run.sh` + - `cleanup_exec` → `cleanup.sh` + +See the [template config file](template-config.md) for reference. For more details on GitLab Runner configuration, consult the [GitLab Runner config documentation][config-page] and [Custom executor documentation][custom-config-page]. + +### 6. Verify SSH key setup + +Confirm that the private SSH key for Orka VM connections is located at `/root/.ssh/id_rsa` on the Runner machine. This key should have been created during your Orka base image setup. + +### 7. Test the installation + +Verify that jq is installed and accessible by entering: `jq --version` [manual-install]: https://docs.gitlab.com/runner/install/osx.html#manual-installation-official [homebrew-install]: https://docs.gitlab.com/runner/install/osx.html#homebrew-installation-alternative [docker-install]: https://docs.gitlab.com/runner/install/docker.html [obtain-token]: https://docs.gitlab.com/ee/ci/runners/#registering-a-specific-runner-with-a-project-registration-token [register-runner]: https://docs.gitlab.com/runner/register/index.html +[config-page]: https://docs.gitlab.com/runner/configuration/ [custom-config-page]: https://docs.gitlab.com/runner/executors/custom.html [jq]: https://stedolan.github.io/jq/ -[runner]: https://docs.gitlab.com/runner/ \ No newline at end of file +[runner]: https://docs.gitlab.com/runner/ diff --git a/GitLab/shell-executor.md b/GitLab/shell-executor.md index f3a73cd..7e6c04d 100644 --- a/GitLab/shell-executor.md +++ b/GitLab/shell-executor.md @@ -1,6 +1,6 @@ # Using a GitLab Shell Executor to Run CI/CD Pipelines in Orka -This guide explains how to set up a GitLab [Shell][shell] executor in a MacStadium [Orka][orka] environment for your GitLab builds. +This guide explains how to set up a GitLab [Shell][shell] executor in a MacStadium [Orka][orka] environment for your GitLab builds. The Shell executor allows you to run builds locally on the machine where the GitLab [Runner][runner] is installed. @@ -32,13 +32,13 @@ The communication between the GitLab Runner and the GitLab server is instantiate This means your Orka environment must have visibility to the GitLab server. -Visibility from the GitLab server to the Orka environment is not required. +Visibility from the GitLab server to the Orka environment is not required. [shell]: https://docs.gitlab.com/runner/executors/shell.html -[orka]: https://orkadocs.macstadium.com/docs/getting-started -[cli]: https://orkadocs.macstadium.com/docs/example-cli-workflows -[api]: https://documenter.getpostman.com/view/6574930/S1ETRGzt?version=latest -[quick-start]: https://orkadocs.macstadium.com/docs/quick-start +[orka]: https://support.macstadium.com/hc/en-us/articles/29904434271387-Orka-Overview +[cli]: https://support.macstadium.com/hc/en-us/articles/42514244203419-Orka3-CLI-Overview-Configuration +[api]: https://macstadium.github.io/orka-api-docs/ +[quick-start]: https://support.macstadium.com/hc/en-us/articles/28347375974555-Orka3-CLI-Quick-Start [runner]: https://docs.gitlab.com/runner/ [manual-install]: https://docs.gitlab.com/runner/install/osx.html#manual-installation-official [homebrew-install]: https://docs.gitlab.com/runner/install/osx.html#homebrew-installation-alternative diff --git a/GitLab/template-config.md b/GitLab/template-config.md index 3ce89ad..c23567a 100644 --- a/GitLab/template-config.md +++ b/GitLab/template-config.md @@ -47,4 +47,4 @@ check_interval = 0 cleanup_exec = "{ cleanup_exec_path }" ``` -[config-page]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html \ No newline at end of file +[config-page]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html