`push`

Use the push command with either the Reunite or Workflows families of products. Pick the section that relates to the product you use.

This command is used to push files from another location to a Reunite project.

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.

Before you begin

Have the following values ready to use with the push command:

A user account in a Reunite project.
An active organization API key.
Redocly CLI installed.

Use the REDOCLY_AUTHORIZATION environment variable to set the API key. See the Manage API keys page in the documentation for details on how to get your API key in Reunite.

Command usage

REDOCLY_AUTHORIZATION=<api-key> redocly push <files> --organization <organizationSlug> --project <projectSlug> --mount-path <mountPath> --branch <branch> --message <message> --author <'Author Name <author-email@example.com>'> [--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	Description
files	[string]	REQUIRED. List of folders and/or files to upload.
--organization, -o	string	REQUIRED. Organization slug.
--project, -p	string	REQUIRED. Project slug.
--mount-path, -mp	string	REQUIRED. The path where the files are mounted in the project.
--branch, -b	string	REQUIRED. The branch files are pushed from.
--author, -a	string	REQUIRED. The author of the push in the format: `'Author Name <author-email@example.com>'`.
--message, -m	string	REQUIRED. The commit message for the push.
--commit-sha, -sha	string	Commit SHA.
--commit-url, -url	string	Commit URL.
--repository	string	Repository ID. Example: `redocly-cli`.
--namespace	string	Repository owner/organization/workspace. Example: `Redocly`.
--created-at	string	Commit creation date. Format: `yyyy-mm-ddThh:mm:ss+offset value`. Example: `2024-02-20T14:26:26+02:00`
--domain	string	The domain to which the files are pushed. Default value is https://app.cloud.redocly.com.
--default-branch	string	The default branch of the repository the push originates from. Default value is `main`.
--lint-config	string	Severity level for configuration file linting. Possible values: `warn`, `error`, `off`. Default value is `warn`.
--max-execution-time	number	Maximum wait time for deployment completion in seconds (used in conjunction with the `--wait-for-deployment` option). Default value is `600`.
--wait-for-deployment	boolean	Waits until the build is completed if it is in progress. Behaves the same as `push-status` command when passed. See push-status command. Default value is `false`.
--verbose	boolean	Verbose output. Default value is `false`.
--help	boolean	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:

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 <user@example.com>" \
          --message "Add new docs"

Pushed files are added to an auto-generated preview branch with a -docs/push-info suffix. The committer is User <user@example.com>, 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, but waits until the preview deployment finishes due to passed --wait-for-deployment option:

REDOCLY_AUTHORIZATION=<api-key> \
redocly push docs/push.yaml \
          --organization default \
          --project 'push-docs' \
          --mount-path 'docs/push' \
          --branch "docs/push-info" \
          --author "User <user@example.com>" \
          --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.

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 to check on an in-progress deploy.
For use in a CI context, check out the GitHub Action.

push