{"id":16752635,"url":"https://github.com/jonasbb/podman-gitlab-runner","last_synced_at":"2025-11-01T15:30:20.331Z","repository":{"id":37566263,"uuid":"234299021","full_name":"jonasbb/podman-gitlab-runner","owner":"jonasbb","description":"Use Podman as a custom executor for your Gitlab CI","archived":true,"fork":false,"pushed_at":"2022-10-27T21:13:40.000Z","size":36,"stargazers_count":94,"open_issues_count":2,"forks_count":20,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-02-10T19:48:22.998Z","etag":null,"topics":["ci","custom-executor","gitlab","gitlab-ci","gitlab-runner","hacktoberfest","podman"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonasbb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-16T10:51:20.000Z","updated_at":"2024-06-16T15:51:15.000Z","dependencies_parsed_at":"2023-01-19T18:16:38.329Z","dependency_job_id":null,"html_url":"https://github.com/jonasbb/podman-gitlab-runner","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fpodman-gitlab-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fpodman-gitlab-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fpodman-gitlab-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonasbb%2Fpodman-gitlab-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonasbb","download_url":"https://codeload.github.com/jonasbb/podman-gitlab-runner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239297756,"owners_count":19615748,"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":["ci","custom-executor","gitlab","gitlab-ci","gitlab-runner","hacktoberfest","podman"],"created_at":"2024-10-13T02:47:41.435Z","updated_at":"2025-11-01T15:30:20.286Z","avatar_url":"https://github.com/jonasbb.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Using Podman to power your Gitlab CI pipeline\n\n**⚠️ NOTE ⚠️**: New deployments should avoid using code from this repository. Instead the official Podman support should be used \u003chttps://docs.gitlab.com/runner/executors/docker.html#use-podman-to-run-docker-commands\u003e.\nOld deployments should consider migrating if possible.\n\n1. [Installation and Setup](#installation-and-setup)\n    1. [Set up rootless Podman for the gitlab-runner user](#set-up-rootless-podman-for-the-gitlab-runner-user)\n    2. [Installing the gitlab-runner](#installing-the-gitlab-runner)\n    3. [Setting up a Runner Instance](#setting-up-a-runner-instance)\n2. [Tweaking the Installation](#tweaking-the-installation)\n    1. [Private Registries](#private-registries)\n3. [License](#license)\n4. [Links](#links)\n\n## Installation and Setup\n\nThe install instructions are for a Fedora 31+ installation.\nMost of the instructions should transfer to other distributions.\ngitlab-runner needs to be installed in version 12.6 or higher, because we rely on the `image` tag being exposed from the `.gitlab-ci.yml` file.\n\n### Set up rootless Podman for the gitlab-runner user\n\nMake sure you have added entries in `/etc/subuid` and `/etc/subgid` for the gitlab-runner user.\nEnable lingering for the gitlab-runner user with `sudo loginctl enable-linger gitlab-runner`.\nRun `sudo -iu gitlab-runner podman system migrate` to set correct cgroups behavior and silence a warning during job execution.\n\n### Installing the gitlab-runner\n\nFirst, you need to install the [gitlab-runner][gitlab-runner-install] using the instructions listed on the website.\nYou can silence the SELinux warnings, by labelling the binary with the proper `bin_t` type like:\n\n```bash\nsudo chcon -t bin_t /usr/bin/gitlab-runner\n```\n\nEnsure that the gitlab-runner service runs with the appropirate permissions.\nSince we are using Podman in a rootless setup, we can run the service with user privileges instead of root permissions.\nAdd a systemd dropin (`/etc/systemd/system/gitlab-runner.service.d/rootless.conf`):\n\n```ini\n[Service]\nUser=gitlab-runner\nGroup=gitlab-runner\n```\n\n### Setting up a Runner Instance\n\nAs the gitlab-runner user change into the home directory (`/home/gitlab-runner`) and clone this repository.\n\n```bash\ngit clone https://github.com/jonasbb/podman-gitlab-runner\n```\n\nThen follow the [instructions][gitlab-runner-register] to set up a new runner instance:\n\n```bash\nsudo -u gitlab-runner gitlab-runner register \\\n    --url https://my.gitlab.instance/ \\\n    --registration-token $GITLAB_REGISTRATION_TOKEN \\\n    --name \"Podman Runner\" \\\n    --executor custom \\\n    --builds-dir /home/user \\\n    --cache-dir /home/user/cache \\\n    --custom-prepare-exec \"/home/gitlab-runner/podman-gitlab-runner/prepare.sh\" \\\n    --custom-run-exec \"/home/gitlab-runner/podman-gitlab-runner/run.sh\" \\\n    --custom-cleanup-exec \"/home/gitlab-runner/podman-gitlab-runner/cleanup.sh\"\n```\n\n## Tweaking the Installation\n\nCurrently, the scripts do not provide much customization.\nHowever, you can adapt the functions `start_container` and `install_dependencies` to specify how Podman should spawn the containers and how to install the dependencies.\n\nSome behaviour can be tweaked by tweaked by setting the correct environment variables.\nRename the `custom_base.template.sh` file into `custom_base.sh` to make use of the customization.\nThe following variables are supported right now:\n\n* `PODMAN_RUN_ARGS`: Customize how Podman spawns the containers.\n\n### Private Registries\n\nPodman supports access to private registries.\nYou can set the `DOCKER_AUTH_CONFIG` variable under **Settings → CI / CD** and provide the credentials for accessing the private registry.\nDetails how the variable has to look can be found under [using statically defined credentials][gitlab-static-credentials] in the Gitlab documentation.\n\nAdditionally, there are multiple ways to authenticate against Gitlab Registries.\nThe script uses a configured deploy token (via `$CI_DEPLOY_PASSWORD`) to login.\nAlternatively, the CI job also provides access to the registry for the duraion of a single job.\nThe scipt uses variables `$CI_JOB_TOKEN` and `$CI_REGISTRY_PASSWORD`, if available, to log into the registry.\n\nThe four methods are tried in order until one succeeds:\n\n1. `DOCKER_AUTH_CONFIG`\n2. `CI_DEPLOY_PASSWORD`\n3. `CI_JOB_TOKEN`\n4. `CI_REGISTRY_PASSWORD`\n\nMore details about different authentication variants in the official documentation: \u003chttps://docs.gitlab.com/ee/user/packages/container_registry/index.html#authenticate-by-using-gitlab-cicd\u003e\n\n## Using Podman in Podman containers\n\nExecuting Podman inside is useful to test containers or build new images inside the CI.\nBy default the nesting fails, since access to the overlayfs is not possible.\n\nRedHat has a guide how to run Podman inside of Podman containers in both rootful and rootless scenarios:\n\u003chttps://www.redhat.com/sysadmin/podman-inside-container\u003e\n\n## License\n\nLicensed under the [MIT license].\n\n## Links\n\n* \u003chttps://tech.immerda.ch/2019/10/gitlab-ci-with-podman/\u003e  \n    First source describing how to set up Podman and gitlab-runner and the source for these scripts.\n* \u003chttps://docs.gitlab.com/runner/executors/custom.html\u003e  \n    Official documentation about the custom executor feature for Gitlab CI.\n* \u003chttps://docs.gitlab.com/runner/executors/custom_examples/\u003e  \n    Official examples how to use the custom executor feature.\n* \u003chttps://gitlab.com/theodore.goetz/gitlab-executor-podman\u003e\n    Alternative implementation of a Podman executor.\n\n[gitlab-runner-install]: https://docs.gitlab.com/runner/install/linux-repository.html\n[gitlab-runner-register]: https://docs.gitlab.com/runner/register/\n[gitlab-static-credentials]: https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#using-statically-defined-credentials\n[MIT license]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasbb%2Fpodman-gitlab-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonasbb%2Fpodman-gitlab-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasbb%2Fpodman-gitlab-runner/lists"}