Marketplace auth updates

docs/manuals/marketplace/authentication.md

@@ -4,17 +4,20 @@ sidebar_position: 3
 description: How to authenticate to the Upbound Marketplace to access private packages.
 ---
 
-Pulling private packages or pushing packages to an Upbound Marketplace private repository requires authentication to Upbound.
+Pulling private packages or pushing packages to an Upbound Marketplace private
+repository requires authentication to Upbound.
 
 Installing private Kubernetes resources requires an [image pull secret][image-pull-secret].
 
 :::important
-Authenticating to the Upbound Marketplace for private packages requires an [Upbound account][upbound-account].
+Authenticating to the Upbound Marketplace for private packages requires an
+[Upbound account][upbound-account]. 
 :::
 
 ## Prerequisites
 
-Install the [Up command-line][up-command-line] to generate Kubernetes secrets and to use Upbound Marketplace private resources.
+Install the [Up command-line][up-command-line] to generate Kubernetes secrets
+and to use Upbound Marketplace private resources.
 
 ## Log in with the Up command-line
 
@@ -26,7 +29,8 @@ 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:
 
@@ -38,7 +42,8 @@ curl -sL "https://cli.upbound.io" | BIN=docker-credential-up sh
 Read the [up CLI configuration][up-cli-configuration] documentation for more installation options.
 :::
 
-For Docker, add `up` to your Docker `config.json`. This allows your client to use Upbound credentials to interact with the Marketplace:
+For Docker, add `up` to your Docker `config.json`. This allows your client to
+use Upbound credentials to interact with the Marketplace:
 
 ```json
 {
@@ -48,10 +53,59 @@ 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.
+
+:::note
+You can use either the `docker-credential-up` helper **or** robot credentials to
+authenticate to `xpkg.upbound.io`. If you have the credential helper
+configured for `xpkg.upbound.io`, it takes precedence over `docker login` and
+causes auth errors when pushing with robot credentials. Remove or scope it
+before following the steps below. 
+:::
+
+### 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.
+
+<!-- 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.
-The image pull secret authenticates Kubernetes to the Upbound Marketplace, allowing Kubernetes to download and install packages.
+The image pull secret authenticates Kubernetes to the Upbound Marketplace,
+allowing Kubernetes to download and install packages.
 
 Generating an image pull secret requires either a user account _token_.
 
@@ -60,7 +114,8 @@ A user account token uses your current `up login` profile.
 Logging out with `up logout` deactivates the token.
 :::
 
-Use the command `up controlplane pull-secret create` to generate a token and Kubernetes _Secret_ in the _upbound-system_ namespace.
+Use the command `up controlplane pull-secret create` to generate a token and
+Kubernetes _Secret_ in the _upbound-system_ namespace.
 
 ```shell
 up ctp pull-secret create
@@ -89,9 +144,14 @@ Use an image pull secret by providing a <Hover label ="pps"
 line="8">spec.packagePullSecrets</Hover> in a <Hover label="pps"
 line="2">Configuration</Hover> or Provider manifest.
 
-Use an image pull secret by providing a <Hover label="pps" line="8">spec.packagePullSecrets</Hover> in a <Hover label="pps" line="2">Configuration</Hover> or `Provider` manifest.
+Use an image pull secret by providing a <Hover label="pps"
+line="8">spec.packagePullSecrets</Hover> in a <Hover label="pps"
+line="2">Configuration</Hover> or `Provider` manifest.
 
-This example installs a private <Hover label="pps" line="2">Configuration</Hover> named <Hover label="pps" line="6">secret-configuration</Hover> from the Upbound image repository using image pull secret named <Hover label="pps" line="8">package-pull-secret</Hover>.
+This example installs a private <Hover label="pps"
+line="2">Configuration</Hover> named <Hover label="pps"
+line="6">secret-configuration</Hover> from the Upbound image repository using
+image pull secret named <Hover label="pps" line="8">package-pull-secret</Hover>.
 
 <div id = "pps">
 ```yaml {copy-line="all"}
@@ -106,8 +166,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/