diff --git a/.eleventy.js b/.eleventy.js index 0dbdacd..3bd56be 100644 --- a/.eleventy.js +++ b/.eleventy.js @@ -9,6 +9,15 @@ module.exports = function(eleventyConfig) { eleventyConfig.addPassthroughCopy("fonts") eleventyConfig.addShortcode("fas_icon", function(name) { return `` }) + + // List of icons: https://codeberg.org/Codeberg/gitea/src/branch/codeberg/public/img/svg + eleventyConfig.addShortcode("gitea_icon", function(name) { + const fetch = require('node-fetch'); + fetch(`https://codeberg.org/img/svg/${name}.svg`) + .then(res => res.text()) + .then(body => {return svg = body;}); + return svg + }) return { dir: { diff --git a/assets/images/integrations/matrix/webhooks.png b/assets/images/integrations/matrix/webhooks.png new file mode 100644 index 0000000..358f3a6 Binary files /dev/null and b/assets/images/integrations/matrix/webhooks.png differ diff --git a/assets/images/integrations/matrix/webhooks.webp b/assets/images/integrations/matrix/webhooks.webp new file mode 100644 index 0000000..bbdbc7d Binary files /dev/null and b/assets/images/integrations/matrix/webhooks.webp differ diff --git a/content/integrations/index.md b/content/integrations/index.md index e0b7623..413efb0 100644 --- a/content/integrations/index.md +++ b/content/integrations/index.md @@ -9,5 +9,3 @@ eleventyNavigation: These documentation pages contain information on how you can use third-party software with Codeberg. See also [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md) which lists projects that work with Gitea, the software which Codeberg is based on. - -Please note that this is a Work in Progress. diff --git a/content/integrations/matrix.md b/content/integrations/matrix.md new file mode 100644 index 0000000..bdf77b9 --- /dev/null +++ b/content/integrations/matrix.md @@ -0,0 +1,44 @@ +--- +eleventyNavigation: + key: MatrixIntegration + title: Integrating with Matrix + parent: Integrations +--- + +This article will guide you through integrating Codeberg with Matrix, allowing repo updates to be automatically broadcast to your project's Matrix room. + +## Create a new Matrix account +To set up the Matrix integration, it is recommended that you [create a new account](https://app.element.io/#/register) dedicated to broadcasting your repo updates. This will act as a bot account. You can create an account on your preferred Matrix server. + +## Getting an access token +You will need an access token to give Codeberg access to send updates from your dedicated Matrix account. Here's how to do it on the Element web client. + +1. Make sure you are logged in to [Element](https://app.element.io/) with the Matrix account you created earlier in a private/incognito browser window. +2. Click on your account name in the top-left corner, then click on `All Settings` in the dropdown. +3. Optionally, you can set a display name and a profile picture for the account here. +4. Navigate to the `Help & About` tab on the left. +5. Scroll to the bottom and click on latter part of `Access Token: ` in the advanced section. +6. Copy the access token that appears to a safe place. +7. **Do not log out of Element.** This will invalidate your access token. Instead, you can simply close your private/incognito browser. + +> Alternatively, you can get an access token directly from the Matrix API. Read more at [Matrix's documentation](https://www.matrix.org/docs/guides/client-server-api#login). + +## Connecting your repo to your Matrix using webhooks +Now we will connect the Matrix bot to your Codeberg repository. You will need admin permissions for the repo. + + + + webhooks + + +1. In a web browser, go to your repo and click on the {% gitea_icon "octicon-tools" %} `Settings` button on the top right. +2. Navigate to the `Webhooks` settings tab. +3. Click on the `Add Webhook` button and select `Matrix`. +4. Here are explanations for some key fields: + + - Homeserver URL: for example `https://matrix.org` + - Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`. You can find this on Element in the `Advanced` tab for the room settings. + - Access token: paste the access token you got earlier. + - Message type: `m.text` is the most basic type of message which represents text. `m.notice` is intended for bots and [behaves differently](https://matrix.org/docs/spec/client_server/latest#m-notice.). + +Add your webhook, then click on the webhook URL. At the bottom now, there will be a `Test Delivery` button. Click this, and you will receive a message on your Matrix room! \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 9f785c5..41db5c1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -7,7 +7,8 @@ "devDependencies": { "@11ty/eleventy": "^0.12.1", "@11ty/eleventy-navigation": "^0.1.6", - "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1" + "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1", + "node-fetch": "^2.6.1" } }, "node_modules/@11ty/dependency-tree": { @@ -2246,6 +2247,15 @@ "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", "dev": true }, + "node_modules/node-fetch": { + "version": "2.6.1", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz", + "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw==", + "dev": true, + "engines": { + "node": "4.x || >=6.0.0" + } + }, "node_modules/nopt": { "version": "4.0.3", "resolved": "https://registry.npmjs.org/nopt/-/nopt-4.0.3.tgz", @@ -5644,6 +5654,12 @@ "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", "dev": true }, + "node-fetch": { + "version": "2.6.1", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz", + "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw==", + "dev": true + }, "nopt": { "version": "4.0.3", "resolved": "https://registry.npmjs.org/nopt/-/nopt-4.0.3.tgz", diff --git a/package.json b/package.json index 19687a8..8b9d643 100644 --- a/package.json +++ b/package.json @@ -10,6 +10,7 @@ "devDependencies": { "@11ty/eleventy": "^0.12.1", "@11ty/eleventy-navigation": "^0.1.6", - "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1" + "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1", + "node-fetch": "^2.6.1" } }