[{"data":1,"prerenderedAt":171},["ShallowReactive",2],{"seo-verification":3,"blog-woodpecker-ci-and-forgejo-cicd-pipeline-on-a-vps-ma-en":6,"promo-bar-likely":170},{"google":4,"bing":5},"EycwPY2XMyTkVzas3n1ygeNJFGAH513qrMjfDljzsMQ","",{"key":7,"data":8},"blog-woodpecker-ci-and-forgejo-cicd-pipeline-on-a-vps-ma-en",{"id":9,"slug":10,"slugs":11,"title":15,"excerpt":16,"readTime":17,"views":18,"isPinned":19,"noindex":19,"publishedAt":20,"updatedAt":21,"category":22,"categories":26,"featuredImage":28,"bgImage":29,"posterImage":30,"relatedSolution":28,"intro":31,"sections":32,"ctaTitle":103,"ctaBody":104,"ctaButton":105,"ctaUrl":106,"relatedPosts":107},212,"woodpecker-ci-and-forgejo-cicd-pipeline-on-a-vps",{"fr":12,"en":10,"ar":13,"es":14},"woodpecker-ci-pipeline-vps-forgejo","woodpecker-ci-وforgejo-خط-أنابيب-cicd-على-خادم-vps","woodpecker-ci-forgejo-pipeline-cicd-vps","Woodpecker CI and Forgejo: CI\u002FCD pipeline on a VPS","Deploy Woodpecker CI v3 with Forgejo on your VPS: Docker Compose setup, YAML pipelines, secrets, multi-arch runners and OAuth troubleshooting.",12,2,false,"2026-08-02T00:00:00+00:00","2026-11-08T01:13:13+00:00",{"id":18,"name":23,"slug":24,"color":25,"icon":24},"Automation","automatisation","bg-brand-action\u002F10 text-brand-action",[27],{"id":18,"name":23,"slug":24,"color":25,"icon":24},null,"\u002Fblog\u002Fcovers\u002Fbg.svg","\u002Fblog\u002Fcovers\u002Fwoodpecker-ci-pipeline-vps-forgejo-poster.svg","Woodpecker CI is an open source pipeline engine — a community fork of Drone CI under the Apache 2.0 license — designed to pair natively with Forgejo. As of version 3.20 (October 2026), each step runs in an isolated Docker container; at idle, the server uses about 100 MB of RAM and the agent about 30 MB. On a VPS, builds run as close as possible to the git repository: no cloud queue, no minute quota to watch, and no integration secret leaves your network.",[33,37,48,51,54,82,85,88,91,94,97,100],{"type":34,"title":35,"body":36},"h2","Why move from cloud CI to a pipeline on your VPS","Cloud CI services charge per build minute and impose shared queues whose wait time grows with volume. As repositories grow or tests multiply, the bill quickly exceeds the cost of a dedicated VPS. Hosting Forgejo and Woodpecker CI on the same server eliminates this network latency: the runner reads the code locally, without routing through third-party infrastructure. You also control the update cycle — no pricing change or log retention policy applies without your consent. For teams with regulatory or confidentiality constraints, this is a decisive advantage: integration secrets (SSH deployment keys, registry access tokens) never cross your network perimeter. Finally, the Apache 2.0 license ensures the source code remains auditable and the project cannot be locked behind an exclusive commercial offering.",{"type":38,"title":39,"items":40},"ul","What Woodpecker CI brings to a VPS setup",[41,42,43,44,45,46,47],"**Docker isolation per step** — each step runs in its own container with no shared state between jobs; a failing step does not corrupt subsequent ones.","**Minimal memory footprint** — at idle, the server uses about 100 MB of RAM and the agent about 30 MB, leaving most resources for the builds themselves.","**Minimal YAML syntax** — a `.woodpecker.yaml` file at the root of the repository is enough to describe the entire pipeline; the syntax is cleaner than GitHub Actions.","**Native Forgejo integration** — Forgejo's OAuth2 is the only authentication mechanism required; webhooks are registered automatically.","**Multi-architecture without extra plugins** — the `platform: linux\u002Farm64` label, in the `labels` block, routes a job to an ARM64 agent; no additional abstraction needed.","**Centralized secrets per repository or global** — sensitive variables are injected at build time and never appear in the versioned YAML file.","**Apache 2.0 license** — auditable source code, active fork community, no dependency on a proprietary vendor.",{"type":34,"title":49,"body":50},"Measured prerequisites: VPS, Forgejo and networking","Woodpecker CI can be installed on the same VPS as Forgejo or on a dedicated server. For both services combined, plan for at least 1 GB of RAM and 2 GB for comfortable usage with several active repositories in parallel. On the software side: Docker Engine 24 or later, Docker Compose v2 (the `docker compose` command, not `docker-compose`), a dedicated subdomain for Woodpecker — for example `ci.your-domain.com` — pointing to the VPS IP, port 443 open for HTTPS, and SSH access. Forgejo must be reachable from the Woodpecker container: either via the internal Docker network if both services share the same host, or via its public HTTPS URL if Woodpecker is on a separate VPS. Woodpecker CI v3 ships a dedicated Forgejo driver (`WOODPECKER_FORGEJO=true`): use a Forgejo version that is still maintained and, if both services share the host, allow local webhooks in Forgejo (`ALLOWED_HOST_LIST=external,loopback` in the `[webhook]` section of `app.ini`).",{"type":34,"title":52,"body":53},"Woodpecker CI vs Forgejo Actions: when to use which","Forgejo Actions — available since Forgejo v1.19 in experimental mode, progressively stabilized — replicates the GitHub Actions syntax: if your teams already have `.github\u002Fworkflows\u002F` pipelines in production, migration is nearly transparent. Forgejo Actions is the natural choice for a repository fleet that coexists with GitHub or reuses public marketplace actions. Woodpecker CI meets different needs: its YAML syntax is more direct, less burdened with concepts inherited from GitHub, and its server-agent architecture allows decoupling the git forge from the CI engine — useful when multiple forges (Forgejo, Gitea, GitLab) need to share the same runner pool. Woodpecker is also better suited to multi-architecture build scenarios, where you want to explicitly route a job to an ARM or x86 agent. In summary: choose Forgejo Actions if GitHub Actions compatibility is the priority, and Woodpecker CI if you prefer a lean syntax, a decoupled deployment, or a heterogeneous runner pool.",{"type":55,"title":56,"steps":57},"steps","Deploy Woodpecker CI on your VPS",[58,61,64,67,70,73,76,79],{"title":59,"body":60},"Create an OAuth App in Forgejo","In Forgejo, go to Settings → Applications → Manage OAuth2 Applications. Give the application a name (for example `woodpecker`) and set the redirect URL to `https:\u002F\u002Fci.your-domain.com\u002Fauthorize`. Note the Client ID and Client Secret generated; they will be used in the Woodpecker server environment variables.",{"title":62,"body":63},"Generate a shared server-agent secret","Generate a strong random string: `openssl rand -hex 32`. This value will be set as `WOODPECKER_AGENT_SECRET` in both the server and agent services; it authenticates gRPC communication between the two. Store it in a secrets manager or an unversioned `.env` file.",{"title":65,"body":66},"Create the directory and docker-compose.yml","Create the `\u002Fopt\u002Fwoodpecker\u002F` directory and place a `docker-compose.yml` file in it. The `woodpecker-server` service uses the image `woodpeckerci\u002Fwoodpecker-server:v3` and listens on ports 8000 (UI) and 9000 (gRPC): do not publish them on the public IP, the reverse proxy and the agent reach them over the Docker network. Set the variables `WOODPECKER_FORGEJO=true`, `WOODPECKER_FORGEJO_URL` (Forgejo public URL), `WOODPECKER_FORGEJO_CLIENT`, `WOODPECKER_FORGEJO_SECRET`, `WOODPECKER_AGENT_SECRET` and `WOODPECKER_HOST=https:\u002F\u002Fci.your-domain.com`. The `woodpecker-agent` service uses `woodpeckerci\u002Fwoodpecker-agent:v3`, mounts `\u002Fvar\u002Frun\u002Fdocker.sock`, and receives `WOODPECKER_SERVER=woodpecker-server:9000` plus the same `WOODPECKER_AGENT_SECRET`.",{"title":68,"body":69},"Configure the HTTPS reverse proxy","Configure Traefik or Caddy to terminate TLS on `ci.your-domain.com` and proxy to `woodpecker-server:8000`. With Caddy, a minimal block is sufficient: `ci.your-domain.com { reverse_proxy woodpecker-server:8000 }`. Never expose port 8000 directly on the public IP; port 9000 (gRPC) must remain accessible only on the internal Docker network.",{"title":71,"body":72},"Start the stack","In `\u002Fopt\u002Fwoodpecker`, run `docker compose up -d`. Check logs with `docker compose logs -f woodpecker-server` until you see `starting http server ...`. On the agent side, `docker compose logs -f woodpecker-agent` should show `starting Woodpecker agent`, then the agent appears in the agent list of the Woodpecker admin settings; if it does not appear there within thirty seconds, check that `WOODPECKER_AGENT_SECRET` is identical in both services.",{"title":74,"body":75},"Log in and activate the first repository","Open `https:\u002F\u002Fci.your-domain.com` and log in with your Forgejo account via OAuth2. In the dashboard, click \"Add repository\", then select the project to activate. Woodpecker automatically registers a webhook in Forgejo to trigger builds on each push or pull request.",{"title":77,"body":78},"Add the .woodpecker.yaml file to the repository","At the root of the repository, create `.woodpecker.yaml`. A minimal example with three steps: `lint` (image `node:24`, command `npm run lint`), `test` (image `node:24`, command `npm test`) and `deploy` conditional on the `main` branch that runs a remote SSH script. Push the file: a pipeline triggers immediately in Woodpecker and the result appears in the interface and in the commit status in Forgejo.",{"title":80,"body":81},"Verify data persistence","By default, Woodpecker stores its SQLite database inside the container. For a durable installation, mount a named volume on `\u002Fvar\u002Flib\u002Fwoodpecker` in the server service and back up this volume regularly. A restart or image update without a named volume erases build history and the configuration of activated repositories.",{"type":34,"title":83,"body":84},"Writing your first .woodpecker.yaml pipeline","A `.woodpecker.yaml` file describes a sequence of steps executed sequentially in separate Docker containers. Each step has a name, an image, and a list of commands. Steps can share the workspace (the cloned directory) via a volume mounted automatically by Woodpecker. For a Node.js project, a basic pipeline includes a `lint` step (`node:24`, `npm ci && npm run lint`), a `test` step (`node:24`, `npm test`) and a `build` step (`node:24`, `npm run build`). For a Docker project, add a step that uses the official `woodpeckerci\u002Fplugin-docker-buildx` plugin to build and push the image to a registry. Conditional triggering is expressed with the `when` block: `when: { branch: main, event: push }` limits the deploy step to the main branch on direct pushes, excluding pull requests.",{"type":34,"title":86,"body":87},"Secrets and environment variables in pipelines","Woodpecker distinguishes three levels of secrets: repository secrets (visible only in pipelines of the relevant repository), organization secrets (shared by an organization's repositories) and global secrets (accessible to all repositories, reserved for instance administrators, to be created with care). A secret is declared in the dashboard — in the repository's Secrets section — then referenced in the pipeline with the `from_secret` syntax. For example, a deployment SSH key named `deploy_key` is injected into a step via `environment: { SSH_KEY: { from_secret: deploy_key } }`. By default, secrets are not passed to pull request pipelines (unless you enable the `pull_request` event on the secret), preventing exfiltration by a malicious contributor. For non-sensitive variables that need to be shared across multiple repositories, use the `WOODPECKER_ENVIRONMENT` variable at the server level: comma-separated `key:value` pairs defined there are available in all pipelines without declaration in the YAML.",{"type":89,"body":90},"tip","Place the Woodpecker server behind Traefik or Caddy with HTTPS and never expose it directly on port 8000. Keep registration closed (`WOODPECKER_OPEN=false`, the default) or, if you open it, restrict it to your Forgejo organizations with `WOODPECKER_ORGS`; designate administrators with `WOODPECKER_ADMIN`. Store all pipeline secrets (SSH tokens, API keys, Docker registry passwords) in the repository secrets of the Woodpecker dashboard — they are injected as environment variables during the build without appearing in the versioned `.woodpecker.yaml`. Finally, mount a named Docker volume to persist the Woodpecker SQLite database: a restart without a volume erases build history.",{"type":34,"title":92,"body":93},"Multi-architecture runners: x86_64 and ARM64","Woodpecker CI v3 natively supports multi-architecture agents: each agent announces its platform to the server (`linux\u002Famd64`, `linux\u002Farm64`, `linux\u002Farm\u002Fv7`) and the server routes jobs to the matching agent. To declare an ARM64 job, add `labels: { platform: linux\u002Farm64 }` at the workflow level in `.woodpecker.yaml` (the old top-level `platform` key was removed in v3). If you have an ARM VPS (Ampere, Raspberry Pi 4, or Hetzner ARM server) and an x86_64 VPS, deploy an agent on each with the same `WOODPECKER_AGENT_SECRET` and let the server distribute builds. A remote agent reaches the server's gRPC port 9000 over the Internet: encrypt that traffic with TLS (`WOODPECKER_GRPC_SECURE=true` on the agent) and open the port only to the agent's IP. This mechanism is useful for cross-compiling binaries, testing Docker image compatibility across architectures, or validating a system package. The `woodpeckerci\u002Fplugin-docker-buildx` plugin goes further and uses QEMU to produce multi-arch images from a single agent, but native builds on the target architecture are always faster.",{"type":34,"title":95,"body":96},"Troubleshooting: five common errors","Five issues come up repeatedly during Woodpecker CI installation or use. First: the agent does not connect to the server (`agent could not auth`). Most frequent cause: `WOODPECKER_AGENT_SECRET` is not identical in both services. Check variables with `docker compose config | grep WOODPECKER_AGENT_SECRET` (Woodpecker images are built on `scratch`, without an `env` command). Second: OAuth2 login fails with `Error while authenticating against OAuth provider`. Likely cause: the redirect URL in the Forgejo OAuth2 application does not exactly match `WOODPECKER_HOST`. Check for a trailing slash and HTTPS scheme consistency. Third: pipelines stay stuck in `pending`. The agent may be connected but the workflow `labels` (for example `platform`) match no agent; remove the ones that are not needed. Fourth: secrets are not injected into steps. By default, a secret is only passed to `push`, `tag` and `deployment` events, never to pull requests. Check that the triggering event is `push` or `tag`. Fifth: after upgrading to v3.18, old build logs are missing. This version includes a log storage migration that can take a while depending on the number of stored lines: back up the data volume before upgrading, plan for downtime and let the migration finish before concluding that logs are lost.",{"type":34,"title":98,"body":99},"Deploying Woodpecker on a ServOrbit VPS","Woodpecker CI installs manually, using Docker Compose, on a ServOrbit Cloud VPS with a fixed IP. Once the VPS is provisioned, simply point `WOODPECKER_FORGEJO_URL` to your existing Forgejo forge and enter the OAuth2 keys for pipelines to start running. This integration is particularly useful for agencies or technical teams that want to isolate the CI engine from the forge server: Forgejo on one VPS, Woodpecker on a second, the two communicating via HTTPS. VPS resources are adjustable at any time from the client portal — add RAM or vCPU without reinstalling — allowing the runner pool to be sized according to actual build load.",{"type":34,"title":101,"body":102},"From git forge to continuous deployment: a complete sovereign stack","Forgejo manages code, issues and pull request reviews; Woodpecker CI orchestrates test and deployment pipelines. The two communicate via OAuth2 and webhooks on your own network, with no dependency on GitHub, GitLab or a cloud integration service. This self-hosted stack meets the sovereignty requirements of agencies and technical teams that do not want their intellectual property or integration secrets to transit through external platforms. With Woodpecker CI v3 and a maintained Forgejo release, you have a complete development environment — git forge, CI\u002FCD, Docker registry if needed — entirely under your control, on one or two VPS, at a predictable monthly cost and without build-minute quotas.","Launch your CI\u002FCD stack on a ServOrbit VPS","A ServOrbit Cloud VPS with preconfigured Docker and a fixed IP lets you deploy Forgejo and Woodpecker CI in minutes, with resources you can scale as your pipelines grow.","Deploy on a ServOrbit VPS","\u002Fvps-cloud",[108,133,150],{"id":109,"slug":110,"slugs":111,"title":115,"excerpt":116,"readTime":117,"views":118,"isPinned":19,"noindex":19,"publishedAt":119,"updatedAt":120,"category":121,"categories":127,"featuredImage":28,"bgImage":29,"posterImage":129,"relatedSolution":130},74,"host-gitea-on-your-own-vps",{"fr":112,"en":110,"ar":113,"es":114},"heberger-gitea","استضافة-gitea-على-خادم-vps-الخاص-بك","alojar-gitea-en-un-vps","Host Gitea on your own VPS in 2026","Deploy Gitea 1.25 on a VPS with Docker and SSL. Full guide: Gitea Actions CI\u002FCD, Gitea vs Forgejo v16 comparison, daily administration, SSH and HTTPS troubleshooting.",13,1,"2026-04-07T00:00:00+00:00","2026-11-08T16:32:50+00:00",{"id":122,"name":123,"slug":124,"color":125,"icon":126},7,"Self-hosting","self-hosting","bg-indigo-500\u002F10 text-indigo-400","cloud",[128],{"id":122,"name":123,"slug":124,"color":125,"icon":126},"\u002Fblog\u002Fcovers\u002Fheberger-gitea-poster.svg",{"categorySlug":131,"appSlug":132},"development","gitea",{"id":134,"slug":135,"slugs":136,"title":140,"excerpt":141,"readTime":142,"views":143,"isPinned":19,"noindex":19,"publishedAt":144,"updatedAt":145,"category":146,"categories":147,"featuredImage":28,"bgImage":29,"posterImage":149,"relatedSolution":28},75,"host-forgejo-on-your-own-vps",{"fr":137,"en":135,"ar":138,"es":139},"heberger-forgejo","استضافة-forgejo-على-خادم-vps-الخاص-بك","alojar-forgejo-en-un-vps","Self-Host Forgejo on Your VPS: Complete 2025 Guide","Deploy Forgejo on your VPS with Docker, SSL, Actions runners and hardened security. Step-by-step guide for a sovereign Git forge.",10,9,"2026-04-06T00:00:00+00:00","2026-11-08T01:13:14+00:00",{"id":122,"name":123,"slug":124,"color":125,"icon":126},[148],{"id":122,"name":123,"slug":124,"color":125,"icon":126},"\u002Fblog\u002Fcovers\u002Fheberger-forgejo-poster.svg",{"id":151,"slug":152,"slugs":153,"title":157,"excerpt":158,"readTime":159,"views":160,"isPinned":19,"noindex":19,"publishedAt":161,"updatedAt":162,"category":163,"categories":164,"featuredImage":28,"bgImage":29,"posterImage":166,"relatedSolution":167},3,"install-n8n-on-vps-with-docker-complete-2026-guide",{"fr":154,"en":152,"ar":155,"es":156},"installer-n8n-vps","تثبيت-n8n-على-vps-مع-docker-دليل-شامل-2026","instalar-n8n-en-vps-con-docker","Install n8n on VPS with Docker: complete 2026 guide","Deploy n8n on VPS with Docker, reverse proxy and HTTPS. Covers V8 crash, 502 nginx, npm migration and execution security (GHSA-vrv8-j27g-g7cr advisory, August 2026).",19,4,"2026-06-05T00:00:00+00:00","2026-11-09T20:55:18+00:00",{"id":18,"name":23,"slug":24,"color":25,"icon":24},[165],{"id":18,"name":23,"slug":24,"color":25,"icon":24},"\u002Fblog\u002Fcovers\u002Finstaller-n8n-vps-poster.svg",{"categorySlug":168,"appSlug":169},"automation-workflows","n8n",true,1794270514799]