Add quickstarts and more updates

Signed-off-by: Jason Tang <[email protected]>

Author: jastang

content/master/guides/extensions-release-process.md

@@ -5,9 +5,24 @@ description: "Configuring build pipelines for Crossplane extensions with GitHub
 Actions"
 ---
 
+## Distributing Crossplane extensions
+
+Crossplane provides a packaging specification for extending a Crossplane
+instance with APIs and business logic for composing resources.
+
 Building a Crossplane extension involves creating OCI images in the [xpkg]
 format. Authors and maintainers of Crossplane extensions must push their
-packages to an OCI registry before Crossplane can reference and use them.
+packages to an OCI registry before users can reference and use them.
+
+The release process for Crossplane extensions grew organically in the community
+and developed its own conventions and common configurations. Authors of these
+extensions should follow this guide to enable automation for building
+and pushing their packages as part of their git workflow.
+
+This guide provides step-by-step instructions for configuring automated
+CI pipelines in GitHub Actions for pushing your Crossplane extensions to
+`xpkg.crossplane.io` and/or `xpkg.upbound.io`, which are two registries
+that the Crossplane community use today.
 
 {{< hint "tip" >}}
 For more information about Crossplane packages, review the
@@ -16,9 +31,6 @@ For more information about Crossplane packages, review the
 
 ## Typical workflow
 
-This guide covers configuring a GitHub Action for building Crossplane
-providers and functions and pushing them to an OCI registry such as `ghcr.io`.
-
 A typical GitHub workflow definition contains the following steps:
 
 1. Fetching the source repository
@@ -31,12 +43,130 @@ The supplied credentials for the remote registry require read and write access
 as upload requests to the registry specify `push` authorization scope.
 {{< /hint >}}
 
-The template GitHub repositories for [providers] and [functions] provide
-a functional GitHub Action in `.github/workflows/ci.yml`. The following
-sections of this guide cover configuration options and conventions for each.
+## Quickstart: Releasing a Provider to `xpkg.crossplane.io`
+
+### Prerequisites
+
+- A GitHub repository, for example created from the
+[Upjet template](https://github.com/crossplane/upjet-provider-template)
+
+### Steps
+
+1. Create a new YAML file under `.github/workflows`. By convention, name this
+file `publish-provider-package.yaml`.
+2. Copy the following workflow definition into the file, replacing
+`<REPOSITORY NAME>` with the desired name of the repository in the registry.
+
+    ```yaml
+    name: Publish Provider Package
+
+    on:
+      workflow_dispatch:
+        inputs:
+          version:
+            description: "Version string to use while publishing the package (e.g. v1.0.0-alpha.1)"
+            default: ''
+            required: false
+          go-version:
+            description: 'Go version to use if building needs to be done'
+            default: '1.23'
+            required: false
+
+    jobs:
+      publish-provider-package:
+        uses: crossplane-contrib/provider-workflows/.github/workflows/publish-provider-non-family.yml@main
+        with:
+          repository: <REPOSITORY NAME>
+          version: ${{ github.event.inputs.version }}
+          go-version: ${{ github.event.inputs.go-version }}
+          cleanup-disk: true
+        secrets:
+          GHCR_PAT: ${{ secrets.GITHUB_TOKEN }}
+    ```
+
+3. Commit the workflow file to the default branch of the GitHub repository.
+4. The workflow should now be available to trigger via the GitHub UI in the
+`Actions` tab.
+
+### Optionally mirroring to `xpkg.upbound.io`
+
+`xpkg.upbound.io` is the registry known as the [Upbound Marketplace].
+
+To optionally push (mirror) the same package to this registry, you need
+an Upbound account.
+
+1. [Log in](https://accounts.upbound.io/login) to Upbound.
+2. Create an [access token](https://accounts.upbound.io/settings/tokens).
+3. Copy the token into a GitHub Actions secret, for example
+`XPKG_UPBOUND_TOKEN`.
+4. Reference the secret created in step 3 in the `secrets` block of the
+workflow YAML file. For example:
+
+    ```yaml
+    secrets:
+      GHCR_PAT: ${{ secrets.GITHUB_TOKEN }}
+      XPKG_UPBOUND_TOKEN: ${{ secrets.XPKG_UPBOUND_TOKEN }}
+    ```
+
+{{< hint "warning" >}}
+The process for optionally pushing to the Upbound Marketplace in this quickstart
+is changing to be consistent with how other pipelines authenticate to
+the Upbound registry.
+
+See https://github.com/crossplane-contrib/provider-workflows/issues/14 for
+details.
+{{< /hint >}}
+
+## Quickstart: Releasing a Function to `xpkg.crossplane.io`
+
+The template repository for [functions] provides a functional GitHub Action
+YAML file that pushes to `xpkg.crossplane.io` without extra configuration.
+
+To optionally configure pushing to the Upbound Marketplace (`xpkg.upbound.io`):
+
+1. [Log in](https://accounts.upbound.io/login) to Upbound.
+2. Create a [Repository](https://docs.upbound.io/build/repositories/store-configurations/#create-a-repository).
+3. Create a [Robot](https://docs.upbound.io/operate/accounts/identity-management/robots/)
+and a [Team](https://docs.upbound.io/operate/accounts/identity-management/teams/).
+4. Assign the Robot to the Team.
+5. Grant the team `WRITE` permission to the repository.
+6. Provision a token (key pair) for the Robot, and save the access ID and token
+as separate GitHub Actions secrets (for example `XPKG_ACCESS_ID` and `XPKG_TOKEN`).
+7. Change the workflow YAML file to authenticate to `xpkg.upbound.io`:
+
+    ```yaml
+      # In env: block
+      XPKG: xpkg.upbound.io/${{ github.repository}}
+      [...]
+
+      # extra login step in the job
+      - name: Login to Upbound
+        uses: docker/login-action@v3
+        if: env.XPKG_ACCESS_ID != ''
+        with:
+          registry: xpkg.upbound.io
+          username: ${{ secrets.XPKG_ACCESS_ID }}
+          password: ${{ secrets.XPKG_TOKEN }}      
+    ```
+
+8. Change the workflow YAML file to push to `xpkg.upbound.io`:
+
+    ```yaml
+      # after login step above
+      - name: Push Multi-Platform Package to Upbound
+        if: env.XPKG_ACCESS_ID != ''
+        run: "./crossplane --verbose xpkg push --package-files $(echo *.xpkg|tr ' ' ,) ${{ env.XPKG }}:${{ env.XPKG_VERSION }}"
+    ```
 
 ## Common Configuration
 
+While the reusable workflows referenced in the quickstart guides are for
+convenience, users may choose to write their own custom GitHub Actions.
+
+This and following sections provide more detailed information
+about common configuration options and conventions to implement the release
+process.
+
 All workflows require references to credentials for a remote registry.
 Typically, users configure them as [GitHub Actions Secrets], and the workflow
 performs authentication via the`docker/login-action`
@@ -97,8 +227,8 @@ where it builds from, and tag it as `v0.1.0`.
 
 {{< hint "note" >}}
 Some custom workflows may accept an explicit input for the remote reference,
-which overrides inferring from a git ref or tag. The [`ci.yml`] file for
-`crossplane-contrib/function-python` is a good example.
+which overrides inferring from a git ref or tag. The [`ci.yml`](https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml)
+file for `crossplane-contrib/function-python` is a good example.
 {{< /hint >}}
 
 ## Configuring workflows for function packages
@@ -155,8 +285,8 @@ registry.
 
 ### Configure target registry
 
-The provider template repository includes a top-level `Makefile`. Edit
-the following variables to define the target registry:
+The provider template repository includes a top-level [`Makefile`](https://github.com/crossplane/upjet-provider-template/blob/main/Makefile).
+Edit the following variables to define the target registry:
 
 1. `XPKG_REG_ORGS` - a space-delimited list of target repositories.
 2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that don't use or infer
@@ -216,8 +346,7 @@ what's configured in GitHub.
 <!-- Named Links -->
 [xpkg]: https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md
 [functions]: https://github.com/crossplane/function-template-go/blob/main/.github/workflows/ci.yml
-[providers]: https://github.com/crossplane/upjet-provider-template/blob/main/.github/workflows/ci.yml
 [GitHub Actions Secrets]: https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions
 [build submodule]: https://github.com/crossplane/build
-[`ci.yml`]: https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml
 [crossplane-contrib/provider-workflows]: https://github.com/crossplane-contrib/provider-workflows/blob/main/.github/workflows
+[Upbound Marketplace]: https://marketplace.upbound.io