From a71e07f71ff56ed150a1c45c359a205fd001f776 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Wed, 10 Jan 2024 08:58:08 +0100 Subject: [PATCH] user: Document README badges Signed-off-by: Gergely Nagy --- docs/user/index.md | 1 + docs/user/readme-badges.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/user/readme-badges.md diff --git a/docs/user/index.md b/docs/user/index.md index 7e37ad1e..3f570479 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -28,6 +28,7 @@ involved in running it on their machines. - [Tags and Releases](https://docs.codeberg.org/git/using-tags/) - [Branch and tag protection](./protection/) - [Git blame](./blame/) + - [README badges](./readme-badges/) - Advanced Usage - [Issue and Pull Request Templates](./issue-pull-request-templates/) - [Actions](./actions/) diff --git a/docs/user/readme-badges.md b/docs/user/readme-badges.md new file mode 100644 index 00000000..cfa84e48 --- /dev/null +++ b/docs/user/readme-badges.md @@ -0,0 +1,20 @@ +--- +title: README badges +license: 'CC-BY-SA-4.0' +--- + +If the [badges service](../../admin/config-cheat-sheet/#badges-badges) is enabled, Forgejo makes it possible to add badges - transparently generated by a service like `shields.io` - to your READMEs and other documentation. These badges let you display useful information about your repository within documentation that might also be displayed elsewhere, outside of the forge itself (such as on container information pages, library documentation sites, and so on). Information such as the latest release, stars, pull request and issue information, or [Actions workflow](../actions/) statuses. + +The badges are returned in SVG format, and are available under the `https://forgejo.example.com/{username}/{repository}/badges` path. Forgejo currently supports generating the following badges: + +- `/release.svg`: The latest release made in the repository. +- `/stars.svg`: The number of stars the repository has. +- `/issues.svg`: The total number of issues in the repository, open and closed combined. +- `/issues/open.svg`: The number of open issues. +- `/issues/closed.svg`: The number of closed issues. +- `/pulls.svg`: The number of pull requests against the repository, open and closed combined. +- `/pulls/open.svg`: The number of open pull requests. +- `/pulls/closed.svg`: The number of closed pull requests. +- `/workflows/{workflow_file}/badge.svg`: The status of the `{workflow_file}` workflow. Additional restrictions can be given for this badge by using the `branch` and/or `event` query parameters. The `branch` query parameter will display the status of the workflow from the given branch (defaulting to the repository's main branch if not explicitly specified), while the `event` parameter will only display results if a run was triggered by the specified event. + +All query parameters not known to Forgejo will be passed along to the badge generator service as-is. If using the default - `shields.io`-based - generator, this means that query parameters such as `style` and `color` will be respected.