|
| 1 | +--- |
| 2 | +title: Forgejo |
| 3 | +weight: 14 |
| 4 | +--- |
| 5 | + |
| 6 | +{{< tech_preview "Forgejo" >}} |
| 7 | + |
| 8 | +# Use Pipelines-as-Code with Forgejo Webhook |
| 9 | + |
| 10 | +Pipelines-as-Code supports [Forgejo](https://forgejo.org) through a webhook. |
| 11 | + |
| 12 | +Forgejo is a community-driven Git forge that originated as a fork of Gitea. Pipelines-as-Code originally supported Gitea and now supports Forgejo, maintaining API compatibility between the two platforms. Both use the same provider type (`gitea`) in Pipelines-as-Code configuration. |
| 13 | + |
| 14 | +Follow the Pipelines-as-Code [installation](/docs/install/installation) according to your Kubernetes cluster. |
| 15 | + |
| 16 | +## Create Forgejo Personal Access Token |
| 17 | + |
| 18 | +Create a Forgejo token for Pipelines-as-Code by going to the Applications tab |
| 19 | +of the user settings, or to this URL (replace the domain name with your domain |
| 20 | +name). |
| 21 | + |
| 22 | +<https://your.forgejo.domain/user/settings/applications> |
| 23 | + |
| 24 | +When creating the token, select these scopes: |
| 25 | + |
| 26 | +### Required Scopes |
| 27 | + |
| 28 | +These scopes are necessary for basic Pipelines-as-Code functionality: |
| 29 | + |
| 30 | +- **Repository** (Write) - For setting commit status and reading repository contents |
| 31 | +- **Issue** (Write) - For creating and editing comments on pull requests |
| 32 | + |
| 33 | +### Optional Scopes |
| 34 | + |
| 35 | +- **Organization** (Read) - Only required if using [team-based policies]({{< relref "/docs/guide/policy" >}}) to restrict pipeline triggers based on Forgejo organization team membership |
| 36 | + |
| 37 | +{{< hint info >}} |
| 38 | +For most users, only the **Required Scopes** are needed. Skip Organization (Read) unless you plan to use `policy.team_ids` in your Repository CRD configuration. |
| 39 | +{{< /hint >}} |
| 40 | + |
| 41 | +Keep the generated token noted somewhere, or otherwise you will have to recreate it. |
| 42 | + |
| 43 | +## Create a `Repository` and configure webhook |
| 44 | + |
| 45 | +{{< hint info >}} |
| 46 | +The `tkn pac create repo` and `tkn pac webhook` commands do not currently support Forgejo. You must configure the webhook manually. |
| 47 | +{{< /hint >}} |
| 48 | + |
| 49 | +### Configure webhook manually |
| 50 | + |
| 51 | +1. From your Forgejo repository, go to **Settings** -> **Webhooks** and click **Add Webhook** -> **Forgejo**. |
| 52 | + |
| 53 | +2. Set the **HTTP method** to **POST** and **POST content type** to **application/json**. |
| 54 | + |
| 55 | +3. Set the **Target URL** to the Pipelines-as-Code controller public URL. On OpenShift, you can get the public URL like this: |
| 56 | + |
| 57 | + ```shell |
| 58 | + echo https://$(oc get route -n pipelines-as-code pipelines-as-code-controller -o jsonpath='{.spec.host}') |
| 59 | + ``` |
| 60 | + |
| 61 | + _If you are not using OpenShift you will need to get the public route from your ingress controller._ |
| 62 | + |
| 63 | +4. Set a **Secret** or generate a random one with: |
| 64 | + |
| 65 | + ```shell |
| 66 | + head -c 30 /dev/random | base64 |
| 67 | + ``` |
| 68 | + |
| 69 | +5. Select the following **Trigger On** events under **Custom events...** (these map to the events Pipelines-as-Code processes): |
| 70 | + |
| 71 | + **Repository events:** |
| 72 | + - Push |
| 73 | + |
| 74 | + **Pull request events:** |
| 75 | + - Opened |
| 76 | + - Reopened |
| 77 | + - Synchronized |
| 78 | + - Label updated |
| 79 | + - Closed |
| 80 | + |
| 81 | + **Issue events:** |
| 82 | + - Comments (only comments on open pull requests are processed) |
| 83 | + |
| 84 | +6. Click **Add Webhook**. |
| 85 | + |
| 86 | +### Create the Secret |
| 87 | + |
| 88 | +Create a secret with the personal token and webhook secret in your target namespace: |
| 89 | + |
| 90 | +```shell |
| 91 | +kubectl -n target-namespace create secret generic forgejo-webhook-config \ |
| 92 | + --from-literal provider.token="TOKEN_AS_GENERATED_PREVIOUSLY" \ |
| 93 | + --from-literal webhook.secret="SECRET_AS_SET_IN_WEBHOOK_CONFIGURATION" |
| 94 | +``` |
| 95 | + |
| 96 | +If you configured an empty webhook secret, use an empty string: |
| 97 | + |
| 98 | +```shell |
| 99 | +kubectl -n target-namespace create secret generic forgejo-webhook-config \ |
| 100 | + --from-literal provider.token="TOKEN_AS_GENERATED_PREVIOUSLY" \ |
| 101 | + --from-literal webhook.secret="" |
| 102 | +``` |
| 103 | + |
| 104 | +### Create the Repository CRD |
| 105 | + |
| 106 | +Create a [`Repository CRD`](/docs/guide/repositorycrd) with the secret field referencing it: |
| 107 | + |
| 108 | +```yaml |
| 109 | +--- |
| 110 | +apiVersion: "pipelinesascode.tekton.dev/v1alpha1" |
| 111 | +kind: Repository |
| 112 | +metadata: |
| 113 | + name: my-repo |
| 114 | + namespace: target-namespace |
| 115 | +spec: |
| 116 | + url: "https://forgejo.example.com/owner/repo" |
| 117 | + git_provider: |
| 118 | + # Use "gitea" as the type - Forgejo is API-compatible with Gitea |
| 119 | + type: "gitea" |
| 120 | + # Set this to your Forgejo instance URL |
| 121 | + url: "https://forgejo.example.com" |
| 122 | + secret: |
| 123 | + name: "forgejo-webhook-config" |
| 124 | + # Set this if you have a different key in your secret |
| 125 | + # key: "provider.token" |
| 126 | + webhook_secret: |
| 127 | + name: "forgejo-webhook-config" |
| 128 | + # Set this if you have a different key in your secret |
| 129 | + # key: "webhook.secret" |
| 130 | +``` |
| 131 | + |
| 132 | +## Notes |
| 133 | + |
| 134 | +- **Provider Type**: Use `type: "gitea"` in your Repository CRD. Forgejo is a fork of Gitea and maintains full API compatibility. |
| 135 | + |
| 136 | +- **Forgejo Instance URL**: You must specify `git_provider.url` pointing to your Forgejo instance URL. |
| 137 | + |
| 138 | +- **Webhook Secret**: Pipelines-as-Code currently does not validate webhook signatures for Forgejo/Gitea. Secrets can be stored, but requests are accepted without signature verification. |
| 139 | + |
| 140 | +- The `git_provider.secret` key cannot reference a secret in another namespace. Pipelines-as-Code always assumes it will be in the same namespace where the `Repository` has been created. |
| 141 | + |
| 142 | +## Update Token |
| 143 | + |
| 144 | +When you have regenerated a new token, you must update it in the cluster. You can find the secret name in the `Repository` CR: |
| 145 | + |
| 146 | +```yaml |
| 147 | +spec: |
| 148 | + git_provider: |
| 149 | + secret: |
| 150 | + name: "forgejo-webhook-config" |
| 151 | +``` |
| 152 | +
|
| 153 | +Update the secret: |
| 154 | +
|
| 155 | +```shell |
| 156 | +kubectl -n target_namespace patch secret forgejo-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}" |
| 157 | +``` |
0 commit comments