From b334d6a407de934b7f27eb37792d24ecce0dea5d Mon Sep 17 00:00:00 2001
From: Rae Sharp <resharp20@gmail.com>
Date: Fri, 15 May 2026 18:10:40 -0400
Subject: [PATCH 1/4] Updates marketplace auth instructions

Signed-off-by: Rae Sharp <resharp20@gmail.com>
---
 docs/manuals/marketplace/authentication.md    | 43 +++++++++++++++++++
 .../repositories/publish-packages.md          |  4 ++
 2 files changed, 47 insertions(+)

diff --git a/docs/manuals/marketplace/authentication.md b/docs/manuals/marketplace/authentication.md
index caedd0262..c0333b775 100644
--- a/docs/manuals/marketplace/authentication.md
+++ b/docs/manuals/marketplace/authentication.md
@@ -48,6 +48,47 @@ For Docker, add `up` to your Docker `config.json`. This allows your client to us
 }            
 ```
 
+## Authenticate to push packages
+
+Pushing packages to the Upbound Marketplace requires a robot token.
+Personal API tokens and `up login` credentials don't work for pushing — they return a 401 error.
+
+### Create a robot token
+
+1. Go to `https://accounts.upbound.io/o/<your-org>/robots` and create a robot account.
+
+2. Copy the robot's **access ID** and **token** — you can't retrieve the token again after leaving the page.
+
+3. Assign the robot to a team that has write permission on the target repository.
+   See [manage repository permissions][team-repo-permissions] for instructions.
+
+### Log in with docker
+
+Use `docker login` with the robot credentials:
+
+```shell
+docker login xpkg.upbound.io -u <robot-access-id> -p <robot-token>
+```
+
+You can now run `crossplane xpkg push` to push packages to the Marketplace.
+
+:::warning
+If you have the `docker-credential-up` helper configured for `xpkg.upbound.io`, it may override the robot credentials. Remove or scope it if you encounter auth errors after a successful `docker login`.
+:::
+
+### Authenticate in CI
+
+In a CI pipeline, use the [`docker/login-action`][docker-login-action] with your robot credentials stored as secrets:
+
+```yaml
+- name: Log in to Upbound Marketplace
+  uses: docker/login-action@v3
+  with:
+    registry: xpkg.upbound.io
+    username: ${{ secrets.UPBOUND_ROBOT_ACCESS_ID }}
+    password: ${{ secrets.UPBOUND_ROBOT_TOKEN }}
+```
+
 ## Kubernetes image pull secrets
 
 Packages in private repositories require a Kubernetes image pull secret.
@@ -111,3 +152,5 @@ spec:
 [up-command-line]: /manuals/cli/overview
 [up-cli-configuration]:/manuals/cli/howtos/profile-config/#configure-docker-credential-helper
 [image-pull-secret]: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials
+[team-repo-permissions]: /manuals/platform/teams/#manage-repository-permissions
+[docker-login-action]: https://github.com/docker/login-action
diff --git a/docs/manuals/marketplace/repositories/publish-packages.md b/docs/manuals/marketplace/repositories/publish-packages.md
index a411b1ee2..b35aa6fd0 100644
--- a/docs/manuals/marketplace/repositories/publish-packages.md
+++ b/docs/manuals/marketplace/repositories/publish-packages.md
@@ -73,6 +73,9 @@ The [`crossplane xpkg build` command reference][crossplane-xpkg-build-command-re
 
 ## Push a package to the repository
 
+Before pushing, authenticate to `xpkg.upbound.io` using a robot token.
+Personal API tokens return a 401 error. See [authenticate to push packages][auth-push] for setup steps.
+
 Push a package to the Upbound Marketplace using the `crossplane xpkg push` command.
 
 The `crossplane xpkg push` command requires:
@@ -163,6 +166,7 @@ Upbound supports all annotations specified in the <a href="https://github.com/cr
 
 [up-cli]: /manuals/cli/overview
 [marketplace]: /manuals/marketplace/overview
+[auth-push]: /manuals/marketplace/authentication#authenticate-to-push-packages
 [crossplane-xpkg-build-command-reference]: https://docs.crossplane.io/latest/cli/command-reference/#xpkg-build
 [crossplane-slack]: https://slack.crossplane.io/
 [docker]: https://docs.docker.com/get-docker/

From 9917c116567f911354cf870345766b1ad55b7e72 Mon Sep 17 00:00:00 2001
From: Rae Sharp <resharp20@gmail.com>
Date: Fri, 15 May 2026 18:22:03 -0400
Subject: [PATCH 2/4] Signed-off-by: Rae Sharp <resharp20@gmail.com>

---
 docs/manuals/marketplace/authentication.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/manuals/marketplace/authentication.md b/docs/manuals/marketplace/authentication.md
index c0333b775..f63fded76 100644
--- a/docs/manuals/marketplace/authentication.md
+++ b/docs/manuals/marketplace/authentication.md
@@ -26,7 +26,7 @@ up login
 
 ## Configure Docker to use the up credential helper
 
-If you use Docker or any other OCI client, you can configure it to use Upbound credentials to interact with the Marketplace. If you plan to push packages to the Upbound Marketplace, you can use the credentials acquired via `up login`. 
+If you use Docker or any other OCI client, you can configure it to use Upbound credentials to interact with the Marketplace.
 
 Install the docker-credential-up credential helper:
 

From 6efb6c41d2edf798e373f04661c082e5a5174dd4 Mon Sep 17 00:00:00 2001
From: Rae Sharp <resharp20@gmail.com>
Date: Fri, 15 May 2026 18:24:30 -0400
Subject: [PATCH 3/4] add crossplane cli link

Signed-off-by: Rae Sharp <resharp20@gmail.com>
---
 docs/manuals/marketplace/authentication.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/manuals/marketplace/authentication.md b/docs/manuals/marketplace/authentication.md
index f63fded76..394f7e360 100644
--- a/docs/manuals/marketplace/authentication.md
+++ b/docs/manuals/marketplace/authentication.md
@@ -70,7 +70,7 @@ Use `docker login` with the robot credentials:
 docker login xpkg.upbound.io -u <robot-access-id> -p <robot-token>
 ```
 
-You can now run `crossplane xpkg push` to push packages to the Marketplace.
+You can run [`crossplane xpkg push`][crossplane-xpkg-push] to push packages to the Marketplace.
 
 :::warning
 If you have the `docker-credential-up` helper configured for `xpkg.upbound.io`, it may override the robot credentials. Remove or scope it if you encounter auth errors after a successful `docker login`.
@@ -147,7 +147,7 @@ spec:
 ```
 </div>
 
-
+[crossplane-xpkg-push]: https://docs.crossplane.io/latest/cli/command-reference/#xpkg-push
 [upbound-account]: /manuals/platform/users
 [up-command-line]: /manuals/cli/overview
 [up-cli-configuration]:/manuals/cli/howtos/profile-config/#configure-docker-credential-helper

From c6ec4446bf5e3f8576ecf1f8a39070e6ae9d6365 Mon Sep 17 00:00:00 2001
From: Rae Sharp <resharp20@gmail.com>
Date: Fri, 15 May 2026 18:44:35 -0400
Subject: [PATCH 4/4] Vale

Signed-off-by: Rae Sharp <resharp20@gmail.com>
---
 docs/manuals/marketplace/authentication.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/manuals/marketplace/authentication.md b/docs/manuals/marketplace/authentication.md
index 394f7e360..0983fb47d 100644
--- a/docs/manuals/marketplace/authentication.md
+++ b/docs/manuals/marketplace/authentication.md
@@ -51,13 +51,13 @@ For Docker, add `up` to your Docker `config.json`. This allows your client to us
 ## Authenticate to push packages
 
 Pushing packages to the Upbound Marketplace requires a robot token.
-Personal API tokens and `up login` credentials don't work for pushing — they return a 401 error.
+Personal API tokens and `up login` credentials don't work for pushing.
 
 ### Create a robot token
 
 1. Go to `https://accounts.upbound.io/o/<your-org>/robots` and create a robot account.
 
-2. Copy the robot's **access ID** and **token** — you can't retrieve the token again after leaving the page.
+2. Copy the robot's **access ID** and **token**. You can't retrieve the token again after leaving the page.
 
 3. Assign the robot to a team that has write permission on the target repository.
    See [manage repository permissions][team-repo-permissions] for instructions.
@@ -76,7 +76,9 @@ You can run [`crossplane xpkg push`][crossplane-xpkg-push] to push packages to t
 If you have the `docker-credential-up` helper configured for `xpkg.upbound.io`, it may override the robot credentials. Remove or scope it if you encounter auth errors after a successful `docker login`.
 :::
 
+<!-- vale Microsoft.HeadingAcronyms = NO -->
 ### Authenticate in CI
+<!-- vale Microsoft.HeadingAcronyms = YES -->
 
 In a CI pipeline, use the [`docker/login-action`][docker-login-action] with your robot credentials stored as secrets: