System Banners Documentation

data/nav.yml

@@ -316,6 +316,8 @@
           path: "team-management/permissions"
         - name: "Enforce 2FA"
           path: "team-management/enforce-2fa"
+        - name: "System banners"
+          path: "team-management/system-banners"
     - name: "Governance"
       children:
         - name: "Overview"

pages/apis/graphql/cookbooks/organizations.md

@@ -376,3 +376,37 @@ query getActorID{
   }
 }
 ```
+
+## Create & delete system banners (enterprise only)
+
+Create & delete system banners via the `organizationBannerUpsert` & `organizationBannerDelete` mutations.
+
+To create a banner call `organizationBannerUpsert` with the organization's GraphQL id and message.
+
+```graphql
+mutation OrganizationBannerUpsert {
+  organizationBannerUpsert(input: {
+    organizationId: "organization-id",
+    message: "**Change to 2FA**: On October 1st ECommerce Inc will require 2FA to be set to access all Pipelines. \r\n\r\n---\r\n\r\nIf you have not set already setup 2FA please go to: [https://buildkite.com/user/two-factor](https://buildkite.com/user/two-factor) and setup 2FA now. ",
+  }) {
+    clientMutationId
+    banner {
+      id
+      message
+      uuid
+    }
+  }
+}
+```
+
+To remove the banner call `organizationBannerDelete` with the organization's GraphQL id.
+
+```graphql
+mutation OrganizationBannerDelete {
+  organizationBannerDelete(input: {
+    organizationId: "organization-id"
+  }) {
+    deletedBannerId
+  }
+}
+```

pages/team_management.md

@@ -8,4 +8,5 @@ Managing users and teams in CI/CD is fundamental to collaboration, streamlined p
 
 - [User and team permissions](/docs/team-management/permissions)
 - [Enforce 2FA](/docs/team-management/enforce-2fa)
+- [System banners](/docs/team-management/system-banners) (enterprise only)
 - [Managing API access tokens](/docs/apis/managing-api-tokens) (under the APIs section)

pages/team_management/system_banners.md

@@ -0,0 +1,30 @@
+---
+keywords: docs, tutorials, 2fa
+---
+
+# System banners (enterprise only)
+
+Organization owners can create announcement banners for the organization. Banners
+will be displayed to all organization members at the top of every page in the
+organization.
+
+You can use Markdown to format your message and link to other documentation
+which you may have.
+
+## Steps to creating a banner
+
+- You must be logged in as an Administrator
+- Visit the Organization's [settings page]
+- Add a message to the **System banners** panel
+- Click **Save Banner**
+
+[settings page]: <https://buildkite.com/organizations/~/settings>
+
+## Programmatically creating a system banner
+
+You can create a system banner programmatically via the GraphQL API.
+
+Please review the GraphQL [cookbook] on instructions on how to create
+a banner via the API.
+
+[cookbook]: </docs/apis/graphql/cookbooks/organizations#create-and-delete-system-banners-enterprise-only>