{"id":18936068,"url":"https://github.com/collabora/obs-gitlab-runner","last_synced_at":"2025-04-15T18:31:20.392Z","repository":{"id":56795492,"uuid":"467121682","full_name":"collabora/obs-gitlab-runner","owner":"collabora","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-21T10:30:53.000Z","size":170,"stargazers_count":0,"open_issues_count":15,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-11T18:27:52.925Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/collabora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-07T14:12:04.000Z","updated_at":"2025-03-21T10:30:57.000Z","dependencies_parsed_at":"2025-01-27T13:41:14.229Z","dependency_job_id":"428b5ab4-4fe6-45e8-9088-0fc6544d27be","html_url":"https://github.com/collabora/obs-gitlab-runner","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Fobs-gitlab-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Fobs-gitlab-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Fobs-gitlab-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Fobs-gitlab-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/collabora","download_url":"https://codeload.github.com/collabora/obs-gitlab-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249129040,"owners_count":21217274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T12:05:48.569Z","updated_at":"2025-04-15T18:31:20.053Z","avatar_url":"https://github.com/collabora.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OBS GitLab Runner\n\nThis is a custom [GitLab Runner](https://docs.gitlab.com/runner/) implementation\nexposing a custom command language for starting, monitoring, and cleaning up\nbuilds on [OBS](https://build.opensuse.org/), specifically targeting Debian\npackages.\n\n## Usage\n\n### Sending Jobs\n\nIn order to send commands in a job to the runner, set the job's `tags:` to\ninclude the tag you used during [the deployment](#deployment), e.g.:\n\n```yaml\nmy-job:\n  tags:\n    - obs-runner  # \u003c-- set to run on runners tagged \"obs-runner\"\n  stage: some-stage\n  script:\n    # [...]\n```\n\nThis will run all the commands inside `before_script`, `script`, and\n`after_script` with the runner.\n\n### Supported Syntax\n\nA subset of shell syntax is supported for commands:\n\n- Commands are split at spaces, but parts can be quoted, just like in the shell:\n  ```bash\n  some-command this-is-argument-1 \"this entire string is argument 2\"\n  ```\n- Variable substitution is supported, as well as the `${VARIABLE:-DEFAULT}`\n  syntax to use the value `DEFAULT` if `$VARIABLE` is unset:\n  ```bash\n  some-command $a_variable ${a_variable_with_default:-this is used if unset}\n  ```\n  The variables are sourced from the pipeline-wide and job-specific variables\n  set.\n  - A significant departure from shell argument parsing is that **variable\n    contents are auto-quoted, thus spaces inside a variable do not split\n    arguments**. For example, given `MYVAR=a b c`, this:\n    ```bash\n    some-command $MYVAR\n    ```\n    is interpreted as:\n    ```bash\n    some-command 'a b c'\n    ```\n    *not*:\n    ```bash\n    some-command a b c\n    ```\n    There is no way to use a variable without auto-quoting its contents.\n\n#### Flags\n\nAny flag arguments shown below can also explicitly take a true/false value, e.g.\n`--rebuild-if-unchanged`, `--rebuild-if-unchanged=true`, and\n`--rebuild-if-unchanged=false`. This is primarily useful to conditionally set\nthe value for a flag; you can set `SOME_VARIABLE=true/false` in your GitLab\npipeline, then use that variable in a flag value as `--flag=$SOME_VARIABLE`.\n\n### Required Environment\n\nIn order to connect to OBS, three variables must be set (generally within the\n\"CI/CD\" section of the settings):\n\n- `OBS_SERVER`: The URL of the OBS instance, e.g. `https://obs.somewhere.com/`.\n- `OBS_USER`: The username used to authenticate with OBS (any commits created\n  will also be under this user).\n- `OBS_PASSWORD`: The password used to authenticate the above username. Although\n  there are no places where this value should be logged, **for safety purposes,\n  it is highly recommended to mark this variable as *Masked*.**.\n\n### Commands\n\n#### `dput`\n\n```bash\ndput PROJECT DSC_FILE\n  [--branch-to BRANCHED_PROJECT]\n  [--build-info-out BUILD_INFO_FILE=build-info.yml]\n  [--rebuild-if-unchanged]\n```\n\nThis will upload the given .dsc file, as well as any files referenced by it, to\nOBS. If any previous .dsc files are present, they, and all files referenced\nwithin, will be removed.\n\nMetadata information on the uploaded revision, such as the revision number,\nproject name, and package name, will be saved into the file specified by\n`--build-info-out` (default is `build-info.yml`). This file is **required** by\nthe `generate-monitor` and `prune` steps. Do note that, if `--branch-to` is\ngiven, the file will be written *immediately* after the branch takes place (i.e.\nbefore the upload); that way, if the upload fails, the branched project can still\nbe cleaned up.\n\n##### `--branch-to BRANCHED_PROJECT`\n\nBefore starting an upload,\n[branch](https://openbuildservice.org/help/manuals/obs-user-guide/art.obs.bg.html#sec.obsbg.uc.branchprj)\nthe package to a new project, named with the value passed to the argument. Any\nuploads will now go to the branched project, and `generate-monitor` / `prune`\nwill both used the branched project / package. This is particularly useful to run\ntesting builds on MRs; you can create an OBS branch named after the MR's Git\nbranch, and then builds can take place there without interfering with your main\nprojects.\n\n##### `--build-info-out BUILD_INFO_FILE=build-info.yml`\n\nChanges the filename that the build info will be written to.\n\n##### `--rebuild-if-unchanged`\n\nBy default, if none of the files to be uploaded are new or modified from their\nprevious versions, this will skip any upload, and thus no build will take place.\n`--rebuild-if-unchanged` will modify this behavior to explicitly trigger a\nrebuild when no actual upload takes place.\n\nNote that, if `--branch-to` was specified, this will, in practice, never be\ntriggered: due to the way metadata files are handled, right after a branching\noperation, there will *always* be a change to upload.\n\n#### `generate-monitor`\n\n```bash\ngenerate-monitor RUNNER_TAG\n  [--rules RULES]\n  [--download-build-results-to BUILD_RESULTS_DIR]\n  [--build-info BUILD_INFO_FILE=build-info.yml]\n  [--pipeline-out PIPELINE_FILE=obs.yml]\n  [--job-prefix MONITOR_JOB_PREFIX=obs]\n  [--job-timeout MONITOR_JOB_TIMEOUT]\n  [--artifact-expiration ARTIFACT_EXPIRATION='3 days']\n  [--build-log-out BUILD_LOG_FILE=build.log]\n```\n\nGenerates a [child\npipeline](https://docs.gitlab.com/ee/ci/pipelines/parent_child_pipelines.html)\nfor the purpose of monitoring builds that were started from a [`dput`](#dput)\ncommand. An individual monitoring job will be generated for each repository /\narchitecture combination in the project, with a name of\n`MONITOR_JOB_PREFIX-REPOSITORY-ARCH` (e.g. `obs-default-aarch64`). Because this\ncommand needs to read the generated build info file, this should generally be in\nthe same job as the invocation of [`dput`](#dput). The generated pipeline\nfile can be included in your main pipeline following the standard GitLab\nmechanisms:\n\n```yaml\nobs:\n  needs:\n    - job-that-generated-the-pipeline-file\n  trigger:\n    strategy: depend\n    include:\n      - artifact: obs.yml\n        job: job-that-generated-the-pipeline-file\n```\n\n`RUNNER_TAG` should be the OBS runner's tag; this will be used to run the\ngenerated monitoring jobs on the correct runner. (Unfortunately, the runner\ncannot see its own tags, so it is unable fill this in by itself.)\n\nIf the parent job that invokes the nested yaml (the `obs` job in the above\nexample) has any rules to [avoid duplicate\npipelines](https://gitlab.com/gitlab-org/gitlab/-/issues/299409), those rules\nshould be added to the generated job via [`--rules`](#--rules), otherwise you\nmay get errors claiming the [\"downstream pipeline can not be\ncreated\"](https://gitlab.com/gitlab-org/gitlab/-/issues/276179).\n\nAfter each monitoring job completes, it will save the build log to\n`BUILD_LOG_FILE`. In addition, if `--download-build-results-to` is given, the\nbuild artifacts will be saved to the `BUILD_RESULTS_DIR`. These artifacts will\nall automatically be uploaded to GitLab.\n\n##### `--rules RULES`\n\nTakes a string containing a YAML sequence of mappings to use as\n[rules](https://docs.gitlab.com/ee/ci/yaml/#rules) on the generated jobs.\n\n```yaml\ndput-and-generate:\n  variables:\n    RULES: |\n      - if: $$VAR == 1\n        when: always\n      - when: never\n  script:\n    - dput [...]\n    - generate-package my-tag --rules $RULES\n  # [...]\n```\n\n##### `--download-build-results-to BUILD_RESULTS_DIR`\n\nAfter a monitoring job completes, download the build results from OBS to the\ngiven `BUILD_RESULTS_DIR`, and upload it as a GitLab build artifact..\n\n##### `--build-info BUILD_INFO_FILE=build-info.yml`\n\nSpecifies the name of the build info file to read. In particular, if a different\nbuild info filename was used with `dput` via\n[`--build-info-out`](#--build-info-out), then `--build-info` should be used here\nto specify the same filename.\n\n##### `--pipeline-out PIPELINE_FILE=obs.yml`\n\nChanges the filename of the child pipeline YAML.\n\n##### `--job-prefix MONITOR_JOB_PREFIX=obs`\n\nChanges the prefix that will be prepended to each generated job\n(`MONITOR_JOB_PREFIX-REPOSITORY-ARCH`).\n\n##### `--job-timeout MONITOR_JOB_TIMEOUT`\n\nChanges the timeout for each generated job, using the [job `timeout`\nsetting](https://docs.gitlab.com/ee/ci/yaml/#timeout). If not passed, the\ntimeout will not be set.\n\n##### `--artifact-expiration ARTIFACT_EXPIRATION='3 days'`\n\nChanges the expiration of the build results \u0026 logs.\n\n##### `--build-log-out BUILD_LOG_FILE=build.log`\n\nChanges the filename each monitoring job will save the build log into.\n\n#### `prune`\n\n```bash\nprune\n  [--build-info BUILD_INFO_FILE=build-info.yml]\n  [--ignore-missing-build-info]\n  [--only-if-job-unsuccessful]\n```\n\nIf a branch occurred, deletes the branched package and, if now empty, project,\nusing the information from the build info file. (If no branching occurred, this\ndoes nothing.)\n\n##### `--build-info BUILD_INFO_FILE=build-info.yml`\n\nSpecifies the name of the build info file to read. In particular, if a different\nbuild info filename was used with `dput` via\n[`--build-info-out`](#--build-info-out), then `--build-info` should be used here\nto specify the same filename.\n\n##### `--ignore-missing-build-info`\n\nDon't return an error if the build info file is missing; instead, do nothing.\nThis is primarily useful if `prune` is used inside of `after_script`, as it's\npossible for the command generating the build info to fail before the build info\nis written.\n\n##### `--only-if-job-unsuccessful`\n\nOnly run the prune if a previous command in the same job failed. This is\nprimarily useful if `prune` is used inside of `after_script`, to only remove the\nbranched project/package if e.g. the upload failed.\n\n## Deployment\n\n### Registering the Runner\n\nIn order to use the runner, you must first register it with your GitLab\ninstance. This requires the use of a registration token, which can be obtained\nvia the following steps:\n\n- Enter the GitLab admin area.\n- Navigate to Overview -\u003e Runners.\n- Click \"Register an instance runner\".\n- Copy the registration token within.\n\n(Per-group/-project registration tokens can also be retrieved from the CI/CD\nsettings of the group or project.)\n\nWith this token, you can now register the runner via the [GitLab\nAPI](https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner).\n\nExample using curl:\n\n```bash\ncurl --request POST \"https://$GITLAB_SERVER_URL/api/v4/runners\"  \\\n  --form description='OBS runner' \\\n  --form run_untagged=false \\\n  --form tag_list=obs-runner \\\n  --form token=\"$REGISTRATION_TOKEN\"\n```\n\nhttpie:\n\n```bash\nhttp --form POST \"https://$GITLAB_SERVER_URL/api/v4/runners\" \\\n  description='OBS runner' \\\n  run_untagged=false \\\n  tag_list=obs-runner \\\n  token=\"$REGISTRATION_TOKEN\"\n```\n\n**It is critical that you set `run_untagged=false`,** otherwise this runner\nwill be used for *all* jobs that don't explicitly set a tag, rather than just\nthe jobs explicitly targeting the runner.\n\nThis API call will return a JSON object containing a `token` key, whose value\nis a _runner token_ that is used by the runner to connect to GitLab.\n\n### Docker\n\nDocker images are built on every commit, available at\n`ghcr.io/collabora/obs-gitlab-runner:main`. The entry point takes two arguments:\n\n- The GitLab server URL.\n- The runner token acquired previously.\n\nSimple example usage via the Docker CLI:\n\n```bash\n$ docker run --rm -it ghcr.io/collabora/obs-gitlab-runner:main \\\n    \"$GITLAB_SERVER_URL\" \"$GITLAB_RUNNER_TOKEN\"\n```\n\nIn addition, you can instead opt to set the `GITLAB_URL` and `GITLAB_TOKEN`\nenvironment variables:\n\n```bash\n$ docker run --rm -it \\\n    -e GITLAB_URL=\"$GITLAB_SERVER_URL\" \\\n    -e GITLAB_TOKEN=\"$GITLAB_RUNNER_TOKEN\" \\\n    ghcr.io/collabora/obs-gitlab-runner:main\n```\n\n### Kubernetes\n\nA [Helm](https://helm.sh/) chart has been provided in the `chart/` directory,\ninstallable via:\n\n```bash\n$ helm install \\\n    --set-string gitlab.url=\"$GITLAB_SERVER_URL\" \\\n    --set-string gitlab.token=\"$GITLAB_RUNNER_TOKEN\" \\\n    obs-gitlab-runner chart\n```\n\nUpgrades can skip setting `gitlab.token` to re-use the previously set value:\n\n```bash\n$ helm upgrade \\\n    --set-string gitlab.url=\"$GITLAB_SERVER_URL\" \\\n    obs-gitlab-runner chart\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollabora%2Fobs-gitlab-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcollabora%2Fobs-gitlab-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollabora%2Fobs-gitlab-runner/lists"}