diff --git a/.starmark/project.ini b/.starmark/project.ini new file mode 100644 index 0000000000..c3cca3d53c --- /dev/null +++ b/.starmark/project.ini @@ -0,0 +1,6 @@ +[settings] +siteType=astro-accelerator +images=accelerator +mediaDir=public/docs/img +contentDateField=modDate +publishDateField=pubDate diff --git a/public/docs/i/1000/projects/release-badges/build-release-badge.webp b/public/docs/i/1000/projects/release-badges/build-release-badge.webp new file mode 100644 index 0000000000..54d94d2e34 Binary files /dev/null and b/public/docs/i/1000/projects/release-badges/build-release-badge.webp differ diff --git a/public/docs/i/1000/projects/release-badges/release-badges.webp b/public/docs/i/1000/projects/release-badges/release-badges.webp new file mode 100644 index 0000000000..781d51565b Binary files /dev/null and b/public/docs/i/1000/projects/release-badges/release-badges.webp differ diff --git a/public/docs/i/2000/projects/release-badges/build-release-badge.webp b/public/docs/i/2000/projects/release-badges/build-release-badge.webp new file mode 100644 index 0000000000..ec9c715440 Binary files /dev/null and b/public/docs/i/2000/projects/release-badges/build-release-badge.webp differ diff --git a/public/docs/i/2000/projects/release-badges/release-badges.webp b/public/docs/i/2000/projects/release-badges/release-badges.webp new file mode 100644 index 0000000000..b501a52d87 Binary files /dev/null and b/public/docs/i/2000/projects/release-badges/release-badges.webp differ diff --git a/public/docs/i/600/projects/release-badges/build-release-badge.webp b/public/docs/i/600/projects/release-badges/build-release-badge.webp new file mode 100644 index 0000000000..4901c90af2 Binary files /dev/null and b/public/docs/i/600/projects/release-badges/build-release-badge.webp differ diff --git a/public/docs/i/600/projects/release-badges/release-badges.webp b/public/docs/i/600/projects/release-badges/release-badges.webp new file mode 100644 index 0000000000..21cee1d5ba Binary files /dev/null and b/public/docs/i/600/projects/release-badges/release-badges.webp differ diff --git a/public/docs/i/x/projects/release-badges/build-release-badge.png b/public/docs/i/x/projects/release-badges/build-release-badge.png new file mode 100644 index 0000000000..782f45a3d4 Binary files /dev/null and b/public/docs/i/x/projects/release-badges/build-release-badge.png differ diff --git a/public/docs/i/x/projects/release-badges/release-badges.png b/public/docs/i/x/projects/release-badges/release-badges.png new file mode 100644 index 0000000000..44d68d4969 Binary files /dev/null and b/public/docs/i/x/projects/release-badges/release-badges.png differ diff --git a/public/docs/img/projects/release-badges/build-release-badge.png b/public/docs/img/projects/release-badges/build-release-badge.png new file mode 100644 index 0000000000..ebb9f6c50a Binary files /dev/null and b/public/docs/img/projects/release-badges/build-release-badge.png differ diff --git a/public/docs/img/projects/release-badges/build-release-badge.png.json b/public/docs/img/projects/release-badges/build-release-badge.png.json new file mode 100644 index 0000000000..052c61c89a --- /dev/null +++ b/public/docs/img/projects/release-badges/build-release-badge.png.json @@ -0,0 +1 @@ +{"width":1268,"height":1414,"updated":"2026-06-19T04:57:21.793Z"} \ No newline at end of file diff --git a/public/docs/img/projects/release-badges/release-badges.png b/public/docs/img/projects/release-badges/release-badges.png new file mode 100644 index 0000000000..7ad35d4d03 Binary files /dev/null and b/public/docs/img/projects/release-badges/release-badges.png differ diff --git a/public/docs/img/projects/release-badges/release-badges.png.json b/public/docs/img/projects/release-badges/release-badges.png.json new file mode 100644 index 0000000000..afa2344f89 --- /dev/null +++ b/public/docs/img/projects/release-badges/release-badges.png.json @@ -0,0 +1 @@ +{"width":1432,"height":336,"updated":"2026-06-19T04:57:21.806Z"} \ No newline at end of file diff --git a/src/pages/docs/projects/badges.md b/src/pages/docs/projects/badges.md new file mode 100644 index 0000000000..c97ab8a3b8 --- /dev/null +++ b/src/pages/docs/projects/badges.md @@ -0,0 +1,97 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-06-19 +title: Release Badges +description: How to add deployment status badges to your Git repositories and other external tools. +navOrder: 12 +--- + +Release Badges let you display the deployment status of your projects in external tools like Git repository READMEs, wikis, or dashboards. Each badge shows the latest release version for a specific environment, so your team can see deployment status at a glance without opening Octopus. + +## Enable badges for a project + +Badges are turned off by default. To turn them on: + +1. Navigate to your project and click **Settings**. +2. Toggle **Badges** on. +3. Click **Save**. + +:::figure + +:img{ src="/docs/img/projects/release-badges/release-badges.png" alt="Enable release badges in project settings" } + +::: + +:::div{.warning} +Turning on badges lets anyone with the badge URL view the latest release version and deployment status for the selected environment. No authentication is required, and no other project data is exposed. +::: + +## Build a badge with the badge builder + +After you turn on badges, a **Badge Builder** button appears on the project settings page. The badge builder gives you a visual interface to configure and preview your badge before copying the code. + +1. Click **Badge Builder** on the project settings page. +2. Select the **environment** you want the badge to show status for. +3. Choose a **label** for the left side of the badge: + - **Environment** (default) — shows the environment name + - **Project** — shows the project name + - **Release** — shows the text "Release" +4. Optionally, expand the **Advanced** section to: + - Turn on **Include failed releases** to show the latest release even if it failed, rather than only showing successful releases. + - Choose a **badge style** — flat (default) or flat-square. +5. Copy the generated code from one of the available formats: + - **Markdown** — for Git repository READMEs and wikis + - **HTML** — for web pages + - **URL** — direct link to the badge image + +The preview updates as you change options, so you can see what the badge looks like before you copy it. + +:::figure + +:img{ src="/docs/img/projects/release-badges/build-release-badge.png" alt="Build badges by selecting what you want to display" loading="lazy" } + +::: + +## Badge colors + +The right side of the badge is automatically colored based on the deployment status: + +| Color | Status | +| ----- | ----------------------------------------- | +| Green | Successful deployment | +| Red | Failed, canceled, or timed-out deployment | +| Blue | Deployment in progress or other states | +| Gray | No deployment found | + +## API endpoints + +You can also build badge URLs manually. Both endpoints are anonymous and don't require authentication. They return a 404 if badges aren't turned on for the project. + +### Image endpoint + +Returns an SVG image you can embed directly: + +```text +GET /api/{spaceId}/projects/{projectSlug}/badge/{environmentSlug}/latest_release +``` + +### JSON endpoint + +Returns badge data as JSON. You can use this endpoint to externalize badge rendering through third-party services like [shields.io](https://shields.io), which offloads requests from your Octopus Server. + +```text +GET /api/{spaceId}/projects/{projectSlug}/badge/{environmentSlug}/latest_release.json +``` + +### Query parameters + +| Parameter | Default | Description | +| --------------- | ------------- | ----------------------------------------------------------------- | +| `label` | `environment` | The text on the left side: `environment`, `project`, or `release` | +| `style` | `flat` | The badge style: `flat` or `flat-square` | +| `includeFailed` | `false` | Include failed, canceled, or timed-out releases | +| `tenantId` | | Filter by a specific tenant for multi-tenant deployments | + +## Caching + +Badge responses include HTTP caching headers to reduce load on your Octopus Server. This means badge updates may not appear instantly after a deployment completes.