docs: add the realm push commands (#1654)

* docs: add the realm push commands * Update docs/commands/push-status.md * minor grammar edits * updates links on push command page * docs: reword duplicate headings * docs: run prettier on updated/added markdown files * docs: fix incorrect markdoc syntax * minor wording updates * docs: tidy the formatting * docs: tidy formatting on push-status --------- Co-authored-by: JLekawa <[email protected]> Co-authored-by: Heather Cloward <[email protected]> Co-authored-by: Adam Altman <[email protected]>
Redocly · Aug 23, 2024 · 1e9e58f · 1e9e58f · github-actions · Aug 23, 2024
1 parent 4ca6f6a
commit 1e9e58f
Show file tree

Hide file tree

Showing 4 changed files with 205 additions and 3 deletions.
diff --git a/docs/commands/index.md b/docs/commands/index.md
@@ -27,6 +27,7 @@ Redocly platform commands:
 - [`login`](login.md) Login to the Redocly API registry with an access token.
 - [`logout`](logout.md) Clear your stored credentials for the Redocly API registry.
 - [`push`](push.md) Push an API description to the Redocly API registry.
+- [`push-status`](push-status.md) Track an in-progress push operation to Reunite.
 
 Supporting commands:
 

diff --git a/docs/commands/push-status.md b/docs/commands/push-status.md
@@ -0,0 +1,61 @@
+# `push-status`
+
+This command is used with Reunite products only.
+It provides details about files, deployments, and API scorecards, using a `<pushId>` that is returned by an earlier `push` command.
+
+The `push-status` command can be used whenever the application or process executing a `push` command (without `--wait-for-deployment` option) returns the `pushId`.
+This identifier can be used by subsequent systems to perform custom logic when the deployment is completed.
+
+## Prerequisites
+
+Have the following before you use the `push-status` command:
+
+- A user account in a [Reunite project](https://auth.cloud.redocly.com/).
+- An active organization [API key](https://redocly.com/docs/realm/setup/how-to/api-keys).
+- [Redocly CLI](../installation.md) v1.10.x or later.
+
+## Authentication
+
+Use the `REDOCLY_AUTHORIZATION` environment variable to set the API key.
+See the [Manage API keys](https://redocly.com/docs/realm/setup/how-to/api-keys) page in the documentation for details on how to get your API key in Reunite.
+
+## Usage
+
+```bash
+REDOCLY_AUTHORIZATION=<api-key> redocly push-status <pushId> --organization <orgSlug> --project <projectSlug> [--wait] [--max-execution-time <timeInSeconds>]
+```
+
+## Options
+
+| Option               | Type    | Required | Default value                                                  | Description                                                                                                       |
+| -------------------- | ------- | -------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| pushId               | string  | true     | -                                                              | Identifier of the push you are tracking. Returned as result of the [`push`](./push.md) command.                   |
+| --organization, -o   | string  | true     | -                                                              | [Organization slug](https://redocly.com/docs/realm/setup/how-to/git-providers/gitlab-self-managed#find-org-slug). |
+| --project, -p        | string  | true     | -                                                              | [Project slug](https://redocly.com/docs/realm/setup/how-to/git-providers/gitlab-self-managed#find-org-slug).      |
+| --domain, -d         | string  | false    | [https://app.cloud.redocly.com](https://app.cloud.redocly.com) | The domain that the `push` command pushed to.                                                                     |
+| --wait               | boolean | false    | false                                                          | Waits until the build is completed if it is in progress.                                                          |
+| --max-execution-time | number  | false    | 600                                                            | Maximum wait time for build completion in seconds (used in conjunction with the `--wait` option).                 |
+
+## Examples
+
+When `push` is performed from the repository's default branch, a preview build is automatically followed by a production build; this command can send only the completed builds or wait for uncompleted builds to complete.
+
+### Get the build status of a specific push
+
+The following example command prints the status of completed preview and production builds as well as scorecards if they exist for the push with the ID `push_01hkw0p0wg348n3gtxmv8rt6hy` in the `redocly` organization and `awesome-api-docs` project:
+
+```bash
+REDOCLY_AUTHORIZATION='api-key' redocly push-status push_01hkw0p0wg348n3gtxmv8rt6hy -o=redocly -p=awesome-api-docs
+```
+
+If there are preview or production builds that haven't completed yet for the push ID, they are not included in the output of this command.
+
+### Get build status for a specific push and wait until it is completed
+
+You can configure the `push-status` command to check the deployment statuses of the preview build (and subsequent production build if applicable), and if the builds are not complete, check every 5 seconds until the builds are complete.
+
+The following example command prints the status for the preview and production builds as well as scorecards if they exist for the push with the ID `push_01hkw0p0wg348n3gtxmv8rt6hy` in the `redocly` organization and `awesome-api-docs` project:
+
+```bash
+REDOCLY_AUTHORIZATION='api-key' redocly push-status push_01hkw0p0wg348n3gtxmv8rt6hy -o=redocly -p=awesome-api-docs --wait
+```
diff --git a/docs/commands/push.md b/docs/commands/push.md
@@ -1,12 +1,17 @@
 # `push`
 
-## Introduction
+Use the push command with either the Workflows or Reunite families of products.
+Pick the section that relates to the product you use.
+
+{% tabs %}
+
+{% tab label="Workflows" %}
 
 Redocly Workflows integrates with [popular version control services](https://redocly.com/docs/workflows/sources/) and uses them as the source of your API descriptions to help you automatically validate, build, and deploy API reference docs and developer portals. This approach requires you to give Redocly Workflows access to your repositories.
 
-The Redocly CLI `push` command helps you automate API description updates without granting Redocly Workflows access to your repositories. This is useful when you can't or don't want to grant Redocly Workflows permissions to your repositories, or when your API descriptions are generated automatically from code annotations in a CI/CD pipeline
+The Redocly CLI `push` command helps you automate API description updates without granting Redocly Workflows access to your repositories. This approach is useful when you can't or don't want to grant Redocly Workflows permissions to your repositories, or when your API descriptions are generated automatically from code annotations in a CI/CD pipeline
 
-This allows you to:
+This method allows you to:
 
 - Use Redocly Workflows to preview documentation and portal builds.
 - Manage versions in the API registry.
@@ -324,3 +329,136 @@ The Redocly Workflows interface can help you get started with the `push` command
 1. In **API registry**, select **Add API**.
 1. In the **Definition name** step, provide a name for your new API description.
 1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API description file. Or use the [`redocly push -u` command](#upsert-an-api-with-push) directly from the command-line interface.
+
+{% /tab %}
+
+{% tab label="Reunite" %}
+
+This command is used to push files from another location to a Reunite project.
+
+{% admonition type="warning" name="The content is overwritten" %}
+The content of the destination folder (in other words the `--mount-path`) is overwritten every time changes are detected in comparison to the current content.
+{% /admonition %}
+
+## Before you begin
+
+Have the following values ready to use with the `push` command:
+
+- A user account in a [Reunite project](https://auth.cloud.redocly.com/).
+- An active organization [API key](https://redocly.com/docs/realm/setup/how-to/api-keys).
+- [Redocly CLI](../installation.md) installed.
+
+Use the `REDOCLY_AUTHORIZATION` environment variable to set the API key. See the [Manage API keys](https://redocly.com/docs/realm//setup/how-to/api-keys) page in the documentation for details on how to get your API key in Reunite.
+
+## Command usage
+
+```bash
+REDOCLY_AUTHORIZATION=<api-key> redocly push <files> --organization <organizationSlug> --project <projectSlug> --mount-path <mountPath> --branch <branch> --message <message> --author <'Author Name <[email protected]>'> [--commit-sha <sha>] [--commit-url <url>] [--created-at <commitCreationDate>] [--repository <repositoryId> ] [--namespace <repositoryOrg>] [--default-branch <repositoryDefaultBranch>] [--domain <domain>] [--wait-for-deployment] [--max-execution-time <timeInSeconds>] [--lint-config <warn | error | off>] [--verbose]
+
+```
+
+## Command options
+
+| Option                |   Type   | Required | Default value                                                  | Description                                                                                                                                                  |
+| --------------------- | :------: | -------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| files                 | [string] | true     | -                                                              | List of folders and/or files to upload.                                                                                                                      |
+| --organization, -o    |  string  | true     | -                                                              | [Organization slug](https://redocly.com/docs/realm/setup/how-to/git-providers/gitlab-self-managed#find-org-slug).                                            |
+| --project, -p         |  string  | true     | -                                                              | [Project slug](https://redocly.com/docs/realm/setup/how-to/git-providers/gitlab-self-managed#find-org-slug).                                                 |
+| --mount-path, -mp     |  string  | true     | -                                                              | The path where the files are mounted in the project.                                                                                                         |
+| --branch, -b          |  string  | true     | -                                                              | The branch files are pushed from.                                                                                                                            |
+| --author, -a          |  string  | true     | -                                                              | The author of the push in the format: `'Author Name <[email protected]>'`.                                                                            |
+| --message, -m         |  string  | true     | -                                                              | The commit message for the push.                                                                                                                             |
+| --commit-sha, -sha    |  string  | false    | -                                                              | Commit SHA.                                                                                                                                                  |
+| --commit-url, -url    |  string  | false    | -                                                              | Commit URL.                                                                                                                                                  |
+| --repository          |  string  | false    | -                                                              | Repository ID. Example: `redocly-cli`.                                                                                                                       |
+| --namespace           |  string  | false    | -                                                              | Repository owner/organization/workspace. Example: `Redocly`.                                                                                                 |
+| --created-at          |  string  | false    | -                                                              | Commit creation date. Format: `yyyy-mm-ddThh:mm:ss+offset value`. Example: `2024-02-20T14:26:26+02:00`                                                       |
+| --domain              |  string  | false    | [https://app.cloud.redocly.com](https://app.cloud.redocly.com) | The domain to which the files are pushed.                                                                                                                    |
+| --default-branch      |  string  | false    | main                                                           | The default branch of the repository the push originates from.                                                                                               |
+| --lint-config         |  string  | false    | warn                                                           | Severity level for configuration file linting. <br/> **Possible values:** `warn`, `error`, `off`.                                                            |
+| --max-execution-time  |  number  | false    | 600                                                            | Maximum wait time for deployment completion in seconds (used in conjunction with the `--wait-for-deployment` option).                                        |
+| --wait-for-deployment | boolean  | false    | false                                                          | Waits until the build is completed if it is in progress. Behaves the same as `push-status` command when passed. See [push-status](./push-status.md) command. |
+| --verbose             | boolean  | false    | false                                                          | Verbose output.                                                                                                                                              |
+| --help                | boolean  | false    | -                                                              | Help output for the command.                                                                                                                                 |
+
+## Constraints
+
+- Maximum file size: 10 MB per file
+- Maximum number of files: 100
+
+## Example usage
+
+### Push files to the `push-docs` project in the default organization
+
+The following command pushes the `index.md` and `docs/push.yaml` files to the project with `push-docs` slug belonging to organization with `redocly` slug:
+
+```bash
+REDOCLY_AUTHORIZATION=<api-key> \
+redocly push index.md docs/push.yaml \
+          --organization redocly \
+          --project 'push-docs' \
+          --mount-path 'docs/push' \
+          --branch "docs/push-info" \
+          --author "User <[email protected]>" \
+          --message "Add new docs"
+```
+
+Pushed files are added to an auto-generated preview branch with a `-docs/push-info` suffix.
+The committer is `User <[email protected]>`, and the commit message is `Add new docs`.
+The files are added inside the `docs/push` folder in the project (the folder is created if it doesn't exist yet, if the folder does exist then the contents are overwritten).
+
+### Push file to the `push-docs` project in the `default` organization and wait until it is deployed
+
+This command example does the same as the [previous example](#push-files-to-the-push-docs-project-in-the-default-organization), but waits until the preview deployment finishes due to passed `--wait-for-deployment` option:
+
+```bash
+REDOCLY_AUTHORIZATION=<api-key> \
+redocly push docs/push.yaml \
+          --organization default \
+          --project 'push-docs' \
+          --mount-path 'docs/push' \
+          --branch "docs/push-info" \
+          --author "User <[email protected]>" \
+          --message "Add new docs" \
+          --wait-for-deployment
+```
+
+The command returns when the deployment is completed.
+
+### Push files from a GitHub action to the `push-docs` project in the `Docs` organization and wait until it is deployed
+
+The following command pushes the `docs/museum.yaml` file to the project `push-docs` in the `Docs` organization.
+It uses the variables available in the GitHub actions context to supply information to the destination.
+
+```bash
+npx @redocly/cli push docs/museum.yaml \
+              --organization "Docs" \
+              --project "push-docs" \
+              --mount-path "/docs/remotes/cicd" \
+              --default-branch "${{ github.event.repository.default_branch || github.event.repository.master_branch }}" \
+              --branch "${{ github.ref_name }}" \
+              --author "${{ github.event.head_commit.author.name }} <${{ github.event.head_commit.author.email }}>" \
+              --commit-sha "${{ github.event.head_commit.id }}" \
+              --commit-url "${{ github.event.head_commit.url }}" \
+              --namespace "${{ github.event.repository.owner.login }}" \
+              --repository "${{ github.event.repository.name }}" \
+              --created-at "${{ github.event.head_commit.timestamp }}" \
+              --message "${{ github.event.head_commit.message }}" \
+              --wait-for-deployment
+```
+
+The `docs/museum.yaml` file from the repository the action is running on is added to the `/docs/remotes/cicd` folder. The change is made on behalf of the latest commit author and uses the most recent commit message.
+
+The `--commit-sha`, `--commit-url`, `--namespace`, `--repository` options are used to attach the details of the push to the deployment and are also shown on the Reunite "Deployments" page.
+This information is useful in case you have multiple sources for the pushes.
+
+Whenever a `push` is performed from the default branch (`--branch "${{ github.ref_name }}"` and equals to `--default-branch "${{ github.event.repository.default_branch || github.event.repository.master_branch }}"`) - a production deployment starts automatically after a successful preview deployment.
+In this case the command waits for both deployments to finish.
+
+## Resources
+
+- Use the [push-status command](./push-status.md) to check on an in-progress deploy.
+- For use in a CI context, check out the [GitHub Action](https://redocly.com/docs/realm/setup/reference/reunite-push-action).
+
+{% /tab %}
+{% /tabs %}
diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml
@@ -26,6 +26,8 @@
           page: commands/preview-docs.md
         - label: push
           page: commands/push.md
+        - label: push-status
+          page: commands/push-status.md
         - label: split
           page: commands/split.md
         - label: stats
St.^❔	Category	Percentage	Covered / Total
🟡	Statements	77.5%	4739/6115
🟡	Branches	65.84%	1968/2989
🟡	Functions	71.78%	781/1088
🟡	Lines	77.69%	4471/5755