Forgejo

This page covers how to configure Pipelines-as-Code with Forgejo through a webhook. Use this method to run Tekton pipelines triggered by pull requests and push events on a self-hosted Forgejo instance. Forgejo is a community-driven Git forge that originated as a fork of Gitea, and Pipelines-as-Code supports it as a first-class provider type.

Prerequisites

• A running Pipelines-as-Code installation
• A Forgejo personal access token (see below)
• The public URL of your Pipelines-as-Code controller route or ingress endpoint

Create a Forgejo Personal Access Token

Create a Forgejo token by going to the Applications tab of the user settings, or to this URL (replace the domain name with your domain name):

https://your.forgejo.domain/user/settings/applications

When creating the token, select these scopes:

Required Scopes

These scopes are necessary for basic Pipelines-as-Code functionality:

• Repository (Write) - For setting commit status and reading repository contents
• Issue (Write) - For creating and editing comments on pull requests

Optional Scopes

• Organization (Read) - Only required if using team-based policies to restrict pipeline triggers based on Forgejo organization team membership

Store the generated token in a safe place, or you will have to recreate it.

Webhook Configuration (Manual)

1. From your Forgejo repository, go to Settings -> Webhooks and click Add Webhook -> Forgejo.

2. Set the HTTP method to POST and POST content type to application/json.

3. Set the Target URL to the Pipelines-as-Code controller public URL. On OpenShift, you can get the public URL like this:

   echo https://$(oc get route -n pipelines-as-code pipelines-as-code-controller -o jsonpath='{.spec.host}')

   If you are not using OpenShift you will need to get the public route from your ingress controller.

4. Set a Secret or generate a random one with:

   head -c 30 /dev/random | base64

5. Select the following Trigger On events under Custom events… (these map to the events Pipelines-as-Code processes):

   Repository events:

   • Push

   Pull request events:

   • Opened
   • Reopened
   • Synchronized
   • Label updated
   • Closed

   Issue events:

   • Comments (only comments on open pull requests are processed)

6. Click Add Webhook.

Create the Secret

Create a Kubernetes secret containing your personal token and the webhook secret in your target namespace:

kubectl -n target-namespace create secret generic forgejo-webhook-config \
  --from-literal provider.token="TOKEN_AS_GENERATED_PREVIOUSLY" \
  --from-literal webhook.secret="SECRET_AS_SET_IN_WEBHOOK_CONFIGURATION"

If you configured an empty webhook secret, use an empty string:

kubectl -n target-namespace create secret generic forgejo-webhook-config \
  --from-literal provider.token="TOKEN_AS_GENERATED_PREVIOUSLY" \
  --from-literal webhook.secret=""

Create the Repository CR

Create a Repository CR with the secret field referencing it:

---
apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
  name: my-repo
  namespace: target-namespace
spec:
  url: "https://forgejo.example.com/owner/repo"
  git_provider:
    type: "forgejo"
    # Set this to your Forgejo instance URL
    url: "https://forgejo.example.com"
    secret:
      name: "forgejo-webhook-config"
      # Set this if you have a different key in your secret
      # key: "provider.token"
    webhook_secret:
      name: "forgejo-webhook-config"
      # Set this if you have a different key in your secret
      # key: "webhook.secret"

Notes

• Provider Type: Use type: "forgejo" in your Repository CR. The legacy type: "gitea" is kept as an alias for backwards compatibility.

• Forgejo Instance URL: Specify git_provider.url pointing to your Forgejo instance URL.

• Webhook Secret: Pipelines-as-Code does not currently validate webhook signatures for Forgejo/Gitea. Secrets can be stored, but requests are accepted without signature verification.

• The git_provider.secret key cannot reference a secret in another namespace. Pipelines-as-Code always assumes it is in the same namespace where the Repository CR has been created.

Update Token

When you have regenerated a new token, you must update it in the cluster. You can find the secret name in the Repository CR:

spec:
  git_provider:
    secret:
      name: "forgejo-webhook-config"

Replace $NEW_TOKEN and $target_namespace with your values:

kubectl -n target_namespace patch secret forgejo-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"