Marketplace auth updates

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:
 
@@ -48,6 +48,49 @@ 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.
+
+### 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 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`.
+:::
+
+<!-- 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:
+
+```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.
@@ -106,8 +149,10 @@ 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
 [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

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/