Giter Club home page Giter Club logo

cli's Introduction

go-octopusdeploy Logo

cli

Command Line Interface for Octopus Deploy ๐Ÿ™

GitHub release Go Report


Installation

Linux & macOS - CURL script

In your Terminal, run the following command:

curl -L https://github.com/OctopusDeploy/cli/raw/main/scripts/install.sh | bash

This will install Octopus CLI in /usr/local/bin. Depending on the permission of /usr/local/bin, you may need to provide your sudo password.

If you would like to install to a different location, set the INSTALL_PATH variable accordingly:

curl -L https://github.com/OctopusDeploy/cli/raw/main/scripts/install.sh | INSTALL_PATH=$HOME/bin bash

You can also install a specific version by providing the VERSION variable:

curl -L https://github.com/OctopusDeploy/cli/raw/main/scripts/install.sh | VERSION=v0.4.0 bash

Windows - MSI file

Navigate to latest release on the GitHub releases page and expand the Assets list.

Download and run the file octopus_[version]_Windows_x86_64.msi

Note: At this time, the installer is x64 only. If you are using Windows on ARM, download the manual archive instead.

Windows - Chocolatey

choco install octopus-cli

Note: At this time, the chocolatey package is x64 only. If you are using Windows on ARM, download the manual archive instead.

macOS - Homebrew

brew install octopusdeploy/taps/octopus-cli

The Homebrew package has native support for macOS Intel and Apple Silicon

Linux (debian/ubuntu based distributions)

sudo apt update && sudo apt install --no-install-recommends gnupg curl ca-certificates apt-transport-https && \
sudo install -m 0755 -d /etc/apt/keyrings && \
curl -fsSL https://apt.octopus.com/public.key | sudo gpg --dearmor -o /etc/apt/keyrings/octopus.gpg && \
sudo chmod a+r /etc/apt/keyrings/octopus.gpg && \
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/octopus.gpg] https://apt.octopus.com/ \
  stable main" | \
  sudo tee /etc/apt/sources.list.d/octopus.list > /dev/null && \
sudo apt update && sudo apt install octopus-cli

# for legacy Ubuntu/Debian (< 18.04) use
# sudo apt update && sudo apt install --no-install-recommends gnupg curl ca-certificates apt-transport-https && \
# curl -sSfL https://apt.octopus.com/public.key | sudo apt-key add - && \
# sudo sh -c "echo deb https://apt.octopus.com/ stable main > /etc/apt/sources.list.d/octopus.com.list" && \
# sudo apt update && sudo apt install octopus-cli

Linux (redhat/fedora based distributions)

sudo curl -sSfL https://rpm.octopus.com/octopuscli.repo -o /etc/yum.repos.d/octopuscli.repo && \
sudo yum install octopus-cli

Any Platform - Manual

Download and extract the archive file for your platform from the latest release on the GitHub releases page.

  • macOS (Apple Silicon): octopus_[version]_macOS_arm64.tar.gz
  • macOS (Intel): octopus_[version]_macOS_x86_64.tar.gz
  • Windows (x64): octopus_[version]_Windows_x86_64.zip
  • Linux (x64): octopus_[version]_Linux_x86_64.tar.gz

The archive file simply contains a compressed version of the octopus binary. If you would like to add it to your PATH then you must do this yourself.

Any platform - go install

If you have the go development tools installed, you can run

go install github.com/OctopusDeploy/cli/cmd/octopus@latest

This will download the latest public release of the CLI from our GitHub repository, compile it for your platform/architecture, and install the binary in your GOPATH

Getting Started

To get started with the Octopus CLI, login to your Octopus Server using the following command:

octopus login

This command will walk you through setting the Octopus Server URL, creating an API key (if necessary) and configuring the CLI for use.

Open ID Connect

In automation scenarios such as CI servers, the login command can be used to authenticate using OpenID Connect (OIDC). This involves exchanging an ID token from an OIDC provider (such as GitHub or GitLab) for an Octopus access token.

To login using OIDC, use the following command:

octopus login --server {OctopusServerUrl} --service-account-id {ServiceAccountId} --id-token {IdTokenFromProvider}

For example:

octopus login --server https://my.octopus.app --service-account-id 834a7275-b5b8-42a1-8b36-14f11c8eb55e --id-token eyJhbGciOiJQUzI1NiIs...

This command will perform the token exchange and configure the CLI for use.

See the documentation on OpenID Connect for more information

Overview

This project aims to create a new CLI (written in Go) for communicating with the Octopus Deploy Server.

It does not seek to be a drop-in replacement for the existing CLI which is written in C# using .NET. https://github.com/OctopusDeploy/OctopusCLI

Differences from the .NET CLI (octo)

The new CLI restructures the command line to be more consistent, and fit with convention across other popular CLI apps. It is built on the popular and widely-used Cobra command line processing library.

The new CLI does not intend to replace all features that were supported by the .NET CLI.

Examples:

.NET CLI

octo list-releases
octo create-release

Go CLI

octopus release list
octopus release create

The new CLI supports an "interactive" mode, where it will prompt for input where parameters are not fully specified on the command line.

Documentation

๐Ÿค Contributions

Contributions are welcome! โค๏ธ Please read our Contributing Guide for information about how to get involved in this project.

Developer Guide

Getting Started

First, ensure that you have Go installed, and available in your PATH. To verify this, open a new terminal window and type go version. You should see something similar to go version go1.18.4 windows/amd64

Next, clone this git repository

Next, open the directory you cloned into, navigate into the cmd/octopus directory, and type go build .

cd <your-local-development-dir>
git clone https://github.com/OctopusDeploy/cli
cd cli
cd cmd/octopus
go build .

If successful, the go compiler does not output anything. You should now have an octopus binary (octopus.exe on windows) in your current directory.

Makefile

If you are using a sytem that has make installed, then you can also simpl run make in the cli root folder. The default action for the Makefile is to run go build, as above.

Running the CLI

The CLI needs to authenticate with the octopus server.

You can configure this using the octopus login command from the Getting Started guide above or by setting environment variables.

macOS/Linux:

export OCTOPUS_URL="http://localhost:8050" # replace with your octopus URL
export OCTOPUS_API_KEY="API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # replace with your API key
./octopus space list # should list all the spaces

Windows (powershell):

$env:OCTOPUS_URL="http://localhost:8050" # replace with your octopus URL
$env:OCTOPUS_API_KEY="API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # replace with your API key
./octopus.exe space list # should list all the spaces

Windows (cmd):

set OCTOPUS_URL="http://localhost:8050" # replace with your octopus URL
set OCTOPUS_API_KEY="API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # replace with your API key
octopus.exe space list # should list all the spaces

go-octopusdeploy library

The CLI depends heavily on the go-octopusdeploy library, which manages communication with the Octopus Server via its JSON API.

Code structure

The CLI follows standard go language conventions for packages, and fits around the package structures set out by the Cobra library for commands.

A rough overview is as follows:

cmd/
   octopus/  # Contains the octopus binary

pkg/
   apiclient/ # Utility code used to manage authentication/connection to the octopus server
   cmd/ # contains sub-packages for each cobra command
      account/ # contains commands related to accounts
      environment/ # contains commands related to environments
      ... # more commands
  constants/ # constant values to avoid duplicated strings, ints, etc
  errors/ # internal error objects
  executor/ # See 'architecture' below
  factory/ # "service locator" object used by commands to locate shared services
  output/ # internal utilities which help formatting output
  question/ # See 'architecture' below

testutil/ # internal utility code used by both unit and integration tests
integrationtest/ # Contains integration tests

Testing

Unit tests for packages follow go language conventions, and is located next to the code it is testing.

pkg/
  question/
    input.go
    input_test.go # unit tests for the code contained in input.go

The easiest way to run the tests is to cd pkg and run go test ./.... We find gotestsum provides a nice wrapper around the underlying go test functionality, which you may also prefer.

Integration Tests

Integration tests live outside the pkg structure and operate outside the app. They launch the CLI as a seperate process, and interact with it using stdout and stderr.

Important: Integration tests assume that an Octopus Deploy server is running and accessible. Before running the integration tests you must set the following environment variables, or the tests will fail.

OCTOPUS_TEST_URL="http://localhost:8050" # replace with your octopus URL
OCTOPUS_TEST_APIKEY: "API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # replace with your API key

Important: Integration tests require an admin-level API key.

Important: Integration tests assume an empty Octopus Server database. If your server contains existing data, the tests may fail, and they may modify or delete any existing data.

The easiest way to run the tests is to cd integrationtest and run go test ./... or gotestsum

Guidance and Example of how to create and test new commands

Imagine that the CLI did not contain an "account create" command, and we wished to add one.

We would go about it as follows:

1. Create packages and files for the command, linking in with Cobra.

We would make a /cmd/account/create directory, and within it put create.go

We would implement a func NewCmdCreate(f factory.Factory) *cobra.Command function which set up the command structure, parameters, flags, etc, and link it in with the parent code in account.go

Example:

func NewCmdCreate(f factory.Factory) *cobra.Command {
	cmd := &cobra.Command{
		Use:   "create",
		Short: "Create an account",
		Long:  "Create an account in Octopus Deploy",
		Example: heredoc.Docf("$ %s account create", constants.ExecutableName),
		RunE: func(cmd *cobra.Command, args []string) error {
			return nil // TODO
		},
	}
	cmd.Flags().StringP("name", "n", "", "name for the item")
	cmd.Flags().StringP("description", "d", "", "description for the item")
	return cmd
}

2. Create a Task which encapsulates the command arguments

in the executor package, create a new string constant, and struct to carry the options for your command

const TaskTypeCreateAccount = "createAccount"

type TaskOptionsCreateAccount struct {
    Name           string   // REQUIRED.
    Description    string   // optional
}

Back in your cmd file, write some code which maps values from the command flags, and puts them into the Task structure, then submit it to the excutor which will do the work when you call ProcessTasks

RunE: func(cmd *cobra.Command, args []string) error {
    name := cmd.Flags().GetString("name")
    description := cmd.Flags().GetString("description")

    task := executor.NewTask(executor.TaskTypeCreateAccount, executor.TaskOptionsCreateAccount{
        Name:        name,
        Description: description,
        // etc
    })

    executor.ProcessTasks(f, []executor.Task{ task })
}

3. Extend the executor to handle your new task

Update the code in ProcessTasks to match your new task identifier string, and write a new helper function to do the work (sending data to the octopus server, etc.)

At this point you should have a functioning command which works in automation mode.

4. Write unit tests to ensure your command works as expected

The unit tests for release list are a reasonable place to start with as an example.

5. Implement interactive mode

Return back to your new command's go file (account/create.go in this example)

At a high level, you should create a function which encapsulates the interactive question/answer session, and returns your TaskOptions structure, which you then pass to ProcessTasks

You should pass a reference to the Ask func, which allows you to mock out the Survey library, and then you should write a series of unit tests which ensure that the question/answer session works correctly.

cli's People

Contributors

benpearce1 avatar borland avatar briggs-octo avatar domenicsim1 avatar eddymoulton avatar geofflamrock avatar hnrkndrssn avatar huyphannguyen avatar isaaccalligeros95 avatar jbristowe avatar justin-walsh avatar long-sean avatar nickdechip avatar slewis74 avatar susanpann avatar team-integrations-fnm-bot avatar zentron avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

cli's Issues

Clarity around auto-selection of spaces

The current behavior of the CLI is as follows:

  • If the OCTOPUS_SPACE environment variable is populated, the CLI will always try and use it; If no such space exists, the CLI will fail, rather than prompting for selection

  • The CLI doesn't know whether OCTOPUS_SPACE contains a name or ID, so before doing anything it will go to the server and first search by ID, then by Name.

  • If OCTOPUS_SPACE is not populated, then when running in automation mode the CLI will simply fail

  • If OCTOPUS_SPACE is not populated, when running interactively, the CLI will ask the server for the list of spaces:

    • If there are no spaces, we fail
    • If there is only one space, the CLI will automatically select it
    • If there is more than one space, the CLI will prompt the user to select one.

Q: Should we reverse the space search order, and check by name first and then fallback to ID?

Q: In the case where there is only one space, the CLI simply uses it. It doesn't pay any attention to the notion of "Default Space" that the Octopus server has. Should we consider perhaps only auto-selecting if there is one space and the server says it is the default space?

add: --dry-run flag

Specifying the --dry-run flag will perform all the steps except any permanent actions. This will then result in the cli collecting everything that it normally would and perform any Octopus API calls that would normally happen, except making any permanent changes.

This is very useful to run to allow you to test it out and see what the output would be without modifying anything within Octopus. In our CI pipeline we provide the option to specify a dry-run flag, but at this point in time we skip the steps where permanent changes will be made within Octopus as we don't have the option to pass the --dry-run flag to the cli.

octopus release create --dry-run
octopus release delete --dry-run
octopus account create --dry-run

10,000 Items Scenario

Assume 10,000 items of a particular resource (i.e. environments) are stored in an Octopus Deploy instance. How should the CLI behave and operate in this scenario for various commands (i.e. list)?

Interactive Mode

sequenceDiagram
    Note left of CLI: create results buffer
    CLI->>+Octopus: get first page of results
    Octopus->>+CLI: page 1
    Note left of CLI: append to buffer
    loop for each page
        CLI->>+Octopus: get page n
        Octopus->>+CLI: page n
        Note left of CLI: append to buffer
    end
    actor User
    CLI->>+User: display selector with entire result buffer
Loading

Loading 10,000 items will impact the user experience (UX) in interactive mode; populating a control (i.e. Select or MultiSelect) will be done in a manner that aligns to the Octopus REST API, which supports paging. The CLI will support loading data in a paged manner; it will preload the data to be bound to the selector BEFORE it is displayed to a user. The selector will have the entire dataset that is mandated by the scenario (i.e. "if the customer expects to see 10,000 items then they should get 10,000 items").

The CLI will support a --limit [size] flag to control the size of the item page. Example:

$ octopus environment list --limit 1000

Automation Mode

sequenceDiagram
    CLI->>+Octopus: get first page of results
    Octopus->>+CLI: page 1
    Note left of CLI: print page 1
    loop for each page
        CLI->>+Octopus: get page n
        Octopus->>+CLI: page n
        Note left of CLI: print page n
    end
Loading

In automation mode, the result sets should be unlimited.

Iteration 1: Buffer everything and output to stdout
Iteration 2: Stream to stdout as pages are returned from the Octopus REST API

configure default --no-prompt

It should be possible to configure the cli to default to --no-prompt. When using this cli in ci scripts, the ci scripts will be littered with --no-prompt flags which is not great. We should be able to set this in the config file next to the tool to remove the need to add this to every cli call.

Feature Request: Upload Build Info

Example based on the new syntax with the existing octo build-information command.
octopus package build-info --package utils --version 1.2.3 --file

Octopus API error: The Resource field is required. []

For some unknown reason, we are getting the following error back from the cli

Octopus API error: The Resource field is required. []

This is the the exact call we do, with parameter values

.\octopus.exe release create --project "package-update-downloader" --version "1.0.0-initial-commit.4177" --package-version "1.0.0-initial-commit.4177" --channel "Release" --release-notes "release 1.0.0-initial-commit.4177 commit -- 3c5541f4b71f9263929c7c1d241b6af05791ac05" --space "Default" --no-prompt

Note that the following were set as ENV vars. OCTOPUS_API_KEY and OCTOPUS_URL

I have run the above on Windows, but we see the same happening on Linux.

Network Operations Should Display a Spinner

Survey questions may perform network I/O during an interactive session. When this occurs, the user should be notified (through a spinner) that work is occurring.

  • verify that the spinner can be cancelled (via Ctrl+C)
  • verify the behaviour of the spinner if a timeout occurs

We will use the spinner from briandowns/spinner.

Example

func doWork() {
  s := spinner.New(spinner.CharSets[11])
  s.Start()

  // invoke Octopus REST API (i.e. Go API client)

  s.Stop()
}

Better support for quoted string values in CLI input flags when generating automation commands

Currently, the CLI always uses single quotes when generating automation commands, e.g.

.\octopus release deploy --project 'Soft Drinks' --version '0.0.3' --environment 'Dev' --tenant-tag 'Regions/us-east'

This works well in Powershell, Bash and other unix shells that we are aware of.

However, windows cmd.exe does not like single quotes. Running the exact same command under cmd results in the following error:

Octopus API error: Exception of type 'Octopus.Core.Model.Exceptions.EntityNotFoundException' was thrown. []

(What is happening behind the scenes is that single quoted text is getting sent to the server, which can't find a project starting with a single quoted string).

Goals

  1. It would be nice to not use any quotes for situations where they aren't neccessary. E.g. --environment Dev
  2. Automation command generation should work under cmd.exe

Automation command generation under cmd.exe

cmd.exe is rarely used by developers because it is very outdated, and fairly awful to work with.

Windows 10 ships with powershell builtin, but the default shell on windows remains cmd, and even in cases where it has been changed there are a lot of people habituated to run cmd when they want a command prompt.
Likewise, if someone writes a .bat or .cmd file, these always execute under cmd, even if you've got the latest windows 11 running windows terminal + powershell.

Aside: While this isn't strictly related to windows terminal, windows 11 ships with windows terminal in-box and changes the default launch property to powershell, so people are far less likely to be using cmd on win11.

Windows terminal is not installed by default on Windows Server 2022, and it can't even be installed on Windows Server 2019 or older ( https://stackoverflow.com/questions/68571422/installing-windows-terminal-on-windows-server-2019-datacenter ), and we need to support the CLI running on windows server machines. Powershell is in-box for supported windows server versions, but as above, whether people will actually be running powershell on machines that aren't Win11 is unclear.

Discussion

There's no immediately obvious fix for this.
To make this work under cmd.exe we will need to use double-quotes.

However, we use single quotes by default because using double-quotes under unix shells causes them to perform variable expansion and require escape codes for things like newlines, which might result in broken commands, if we aren't careful in how we handle escape characters.

Furthermore, different shells have different escape rules; for example the escape characters allowed/processed by Bash are not the same as Powershell.

Ideas? (Needs investigation)

We could attempt to create a single double-quoted and escaped output format, aimed at the lowest common denominator between Powershell/Cmd/Bash/Zsh and a few others. It is unclear if this is possible, or if so, whether that would produce nice output.

We could attempt to generate shell-specific commandlines by detecting if we're running under powershell/bash/cmd/whatever and adjusting the output accordingly.
If we do generate shell-specific output then we should also add a config setting to force the setting, in case our detection code misses something, or if someone wants to generate commandlines targeting platforms other than the one they are running on

There may be other ways to handle this, TBD

octopus space delete --confirm does not delete the space

Repro:

  • Create a space
  • run octopus space delete "SpaceNameHere" --confirm
  • Expected: the space to get deleted
  • Observed: the cli just exits with no output or warnings and the space is not deleted

I also tried "--confirm y", "--confirm=yes", "--confirm yes" and other variations like that.

Deleting spaces does work if you don't supply --confirm and go through the interactive confirmation.

Root cause is this code here:

return delete(client, itemToDelete)

The delete function call only runs if it's inside the question DeleteWithConfirmation callback, where it should run on both sides of the if !alreadyConfirmed branch

Select prompts error when there are no options

List-select prompts that have no options will error when there are no options available

e.g error due to target space having no environments

โฏ octopus deployment-target cloud-region create --space test1
? Name cr1
please provide options to select from

Unexpected differences between json and basic cli output (--output-format json not working)

The bug

When creating a release and supplying the flag --output-format json, the response is vastly different to when omitting that flag (thus returning basic string format).

Command to reproduce

Basic formatting

octopus release create  --project "project.name" --version 1.4.4 --package-version 1.4.4 --channel Release --release-notes "auto created from build pipeline." --space "Default" --no-prompt

Successfully created release version 1.4.4.1 using channel Release

View this release on Octopus Deploy: https://octopus.domain.com/app#/Spaces-1/releases/Releases-297773

octopus release create  --project "project.name" --version 1.4.4 --package-version 1.4.4 --channel Release --release-notes "auto created from build pipeline." --space "Default" --no-prompt --output-format json
{"ReleaseNotes":"","Assembled":"0001-01-01T00:00:00Z","Channel":"Release","Version":"1.4.4.1"}

Outcome

The expectation is that in the json output, I would at the very least get back the release id, in this case Releases-297773. Without that we need to now do a second call to try and get the release id, or we need to do string manipulation on the basic output to get the release id / link.

Versions

cli: I don't know as the cli doesn't have a way to tell me what version it is!

Octopus Server: 2023.2

Links

Running runbook via tenant tags results in error

Trying to run a runbook with this command results in an error.

octopus runbook run --space 'Administration' --project 'OctoFX Template' --name 'Deploy a group of releases' --environment 'Administration' --tenant-tag 'Options/Run Daily Deployments' --tenant-tag 'Region/NA' --tenant-tag 'State/Created' --no-prompt

The error is Octopus API error: Sequence contains more than one element []

image

Server is https://demo.octopus.app and is accessible internally.

runbook run command not respecting `--project` argument

The runbook run command seems to ignore the --project argument. Instead of failing if the project doesn't contain a runbook with the name specified in the --name argument, it will find the first runbook with the name and run it. For example, on my local instance, I have two projects, Cassandra Demo and Rancher Demo. Cassandra demo has a runbook with the name Recreate Containers and Rancher Demo has a runbook with the name Remove Namespaces. If I run

 &.\octopus runbook run --project 'Cassandra Demo' --name 'Remove Namespaces' --environment 'Production' --no-prompt --space 'Default'

The Remove Namespaces runbook is run despite it not being in project Cassandra Demo.

Error when working with deployment targets when instance has a k8s target configured

The bug

When working with either of the following commands where the target Octopus Sever contains a k8s target will error:
octopus deployment-target list
octopus deployment-target kubernetes list
octopus deployment-target delete

Command to reproduce

octopus deployment-target list
octopus deployment-target kubernetes list
octopus deployment-target delete

Outcome

cannot get endpoint /api/Spaces-1/machines?take=2147483647&deploymentTargetTypes=Kubernetes from server. failure from http client json: cannot unmarshal string into Go struct field Resources[*github.com/OctopusDeploy/go-octopusdeploy/v2/pkg/machines.DeploymentTarget].Items of type bool

Versions

cli: 1.0+

Octopus Server: any that support k8s targets

Links

Some arguments do not accept the ID instead of the name

The bug

A few commands do not accept the ID of the object I am targeting. I am trying to update one of our custom build tools to this CLI version and we currently rely on the ID's everywhere instead of the name (as we change this sometimes). It would be much preferred if we don't have to specify the name.

Command to reproduce

octopus release create `
  --project 'Projects-423' `
  --channel 'Channels-681' `
  --version='4.35.0.0' `
  --package-version '4.35.0.0 `
  --release-notes 'Automated release' `
  --no-prompt

octopus release deploy `
  --project 'Projects-423' `
  --tenant 'Tenants-708' `
  --environment 'Environments-201 ' `
  --version '4.35.0.0' `
  --force-package-download `
  --no-prompt

Outcome

Octopus API error: Channel named 'Channels-681' within project '<my project name>' was not found.
Octopus API error: Environment named 'Environments-201' within project '<my project name>' was not found.

Versions

cli: 1.4.0
Octopus Server: 2023.3.4135
os: Fedora Linux 38
cli: bash and powershell (latest)

installation fails on ubuntu 22.10

The bug

I'm getting this error when trying to install the package via the documented apt commands. Ubuntu 22.10 includes [libicu71](https://packages.ubuntu.com/kinetic/libicu71) so the dependency tree for octopus probably needs to be updated to support newer ubuntu versions.

Command to reproduce

# after having set up the apt source as documented
sudo apt install octopuscli

Outcome

The following packages have unmet dependencies:
 octopuscli : Depends: libicu52 but it is not installable or
                       libicu55 but it is not installable or
                       libicu57 but it is not installable or
                       libicu60 but it is not installable or
                       libicu63 but it is not installable or
                       libicu66 but it is not installable or
                       libicu67 but it is not installable or
                       libicu70 but it is not installable

Versions

cli: latest available

Octopus Server: N/A

Links

`create release` does not support project slugs via automation mode

The bug

Command to reproduce

octopus release create -p project-2 -c default -v 0.0.10 --no-prompt

Outcome

Octopus API error: Project named 'project-2' was not found. []

When in prompt-mode, it finds the project correctly and works

octopus project view project-2
project 2 (project-2)
Version control branch: Not version controlled
No description provided
View this project in Octopus Deploy: http://localhost:8065/app#/Spaces-1/projects/Projects-21

Versions

cli: all versions

Octopus Server: tested on latest

Links

Provide option to return response/output in json

Currently the cli would print any output/response from the cli in plain text. This is less than ideal as we are using this cli in our ci system. As an example, when we create a release, we then need to parse this output/response from the cli using regex to extract the release id / link.

project create with Config As Code conversion not working as expected.

source: https://octopus.zendesk.com/agent/tickets/105938

doing a project create with Config as Code conversion in a single command in an automation context (when specifying --no-promt) does not perform the CaC conversion.

Example command:

octopus project create --name 'CLI Test Project Part 2' --group 'Default Project Group' --space 'Default' --lifecycle 'Default Lifecycle' --no-prompt --process-vcs --git-credential-store 'library' --git-base-path '.octopus/CLI Test 2' --git-url 'https://github.com/reoName/OctopusCaC.git' --git-branch 'main' --git-initial-commit 'Test commit' --git-credentials 'GitHub' --no-prompt

The interactive mode will correctly generate two commands, project create and project convert that will successfully create and convert the project.

Version parameter chokes on values with `\r` in `octopus release deploy`

I hit an annoying edge case bug.

I have a pipeline that builds some software on Windows and as part of that writes the version string to a text file which I consume in a different job that is running in a Linux container.

> "$build" | Set-Content -Path VERSION.txt

What's weird is I consume this to create the release without issue.

$ octopus release deploy --space Default --project project--version $(cat VERSION.txt) --environment Dev --no-prompt

But when I try to deploy the release, it throws an error.

$ octopus release deploy --space Default --project project --version $(cat VERSION.txt) --environment Dev --no-prompt
Octopus API error: Object reference not set to an instance of an object. []

If I trim any newline characters, it works.

$ octopus release deploy --space Default --project project --version $(cat VERSION.txt|tr -d '\n\r') --environment Dev --no-prompt
Successfully started 1 deployment(s)

First-Run Experience

The first-run experience of the CLI should be forgiving and provide users with the ability to configure it for subsequent runs.

Currently, the CLI assumes the presence of the following environment variables in order to perform operations against Octopus Deploy:

  • OCTOPUS_API_KEY: the API key used to communicate with the Octopus Deploy instance
  • OCTOPUS_HOST: the URI of Octopus Deploy instance
  • OCTOPUS_SPACE: the ID or name of the space in Octopus Deploy

If these environment variables are missing from the host environment, the CLI should prompt the user for these values. It may be warranted to persist these values to the host's environment. (This is an open question; should we do this?)

CLI Configuration

The CLI should support a config command that provides the user to control the CLI configuration.

Commands

  • octopus config get: print the value of a given configuration key
  • octopus config set: update configuration with a value for the given key
  • octopus config list: print a list of configuration keys and values

Configuration Settings

  • api_key: the API key to be used to communicate with Octopus Deploy
  • editor: the text editor program to use for authoring text
  • host: the host URI of Octopus Deploy
  • prompt: toggle interactive prompting in the terminal (default: "enabled")
  • space: the space within which to perform operations in Octopus Deploy

Configuration

Create a file to easily persist common configuration.
This will be achieved using Viper.

The following keys are being considered to include in the configuration file.

Key Default Value Description
Host Octopus Deploy Host
ApiKey Octopus Deploy API key. Note stored as plain text.
Space An Octopus space to use
NoPrompt disabled Disable interactive mode if true
ProxyUrl Set proxy to direct traffic through
Editor unix: nano, windows: notepad The text editor program to use for authoring text
ShowOctopus enabled for first run only Show octopus on root help command
OutputFormat table Output format to enforce

Configuration file will be stored in the following locations:

  • Window: %APPDATA%\Octopus\cli_config.
  • Unix: ~/.config/octopus/cli_config.

Configuration will follow the precedence order enforce by Viper. Each item takes precedence over the item below it:

  1. flag
  2. env
  3. config
  4. key/value store (config file)
  5. default

The following new commands will be created to easily interact with the configuration file:

  • octopus config set
    • set value for key in config file
  • octopus config list [flags]
    • list all values on config file
    • supports output-format flag
  • octopus config get
    • show value for given key

Interactive Mode

octopus config set

? Select the key you would you like to change?
> Host
  Api Key
  Space
...

octopus config set host

? Enter new value for Host: <input>

octopus config get

? Select the key you would you like to see the value of?
> Host
  Api Key
  Space
...

colors are not working properly under windows cmd.exe

Observe attached screenshot:

Colors rendered by Survey are fine.
Colors rendered by our own output functions are not.

image

Interestingly the github CLI is also fine; we'd thought we'd based our color output on theirs, but there must be some difference occurring

octopus config set is broken in interactive mode

Repro on version 0.2.5 of the CLI

Start with a clean system, delete any existing cli_config.json from your home folder

octopus config set
? What key would you like to change? (select ApiKey)

Expected to prompt for input so you can type/paste the api key

Actual: CLI exits with error unable to get value for key: ApiKey

This happens for any config value where an entry doesn't already exist in cli_config.json

`account create` errors

When executing account create (as opposed to account username create), the following error occurs when being asked for the environment scopes

? Account Type Username/Password
? Name up2
? Description <Skipped>
? Username user
? Password [? for help] ****
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x14bffef]

goroutine 1 [running]:
github.com/OctopusDeploy/cli/pkg/question/selectors.EnvironmentsMultiSelect(0x16bb56c?, 0x16b7d9a?, {0xc0002561e0, 0x9e}, 0x80?)
	cli/pkg/question/selectors/environments.go:59 +0x2f
github.com/OctopusDeploy/cli/pkg/cmd/account/username/create.PromptMissing(0xc0001299c0)
	cli/pkg/cmd/account/username/create/create.go:202 +0x625
github.com/OctopusDeploy/cli/pkg/cmd/account/username/create.CreateRun(0xc0001299c0)
	cli/pkg/cmd/account/username/create/create.go:119 +0x3c
github.com/OctopusDeploy/cli/pkg/cmd/account/create.createRun({0x179b728, 0xc000458400}, 0xc00046a000)
	cli/pkg/cmd/account/create/create.go:136 +0x14d6
github.com/OctopusDeploy/cli/pkg/cmd/account/create.NewCmdCreate.func1(0xc00046a000?, {0x168bf72?, 0x0?, 0x0?})
	cli/pkg/cmd/account/create/create.go:27 +0x27
github.com/spf13/cobra.(*Command).execute(0xc00046a000, {0x1bf4600, 0x0, 0x0})
	~/go/pkg/mod/github.com/spf13/[email protected]/command.go:916 +0x862
github.com/spf13/cobra.(*Command).ExecuteC(0xc000401200)
	~/go/pkg/mod/github.com/spf13/[email protected]/command.go:1044 +0x3bd
github.com/spf13/cobra.(*Command).Execute(...)
	~/go/pkg/mod/github.com/spf13/[email protected]/command.go:968
main.main()
	~/git/cli/cmd/octopus/main.go:73 +0x49c

package create command

This command will enable users to create NuGet and ZIP archives from the command line. It should match the feature set found in the pack command in the OctopusCLI.

missing {-v|--version} flag

New CLI missing this important flag:

# octopuscli
$ octo --version
  9.1.7
# octopus-cli
$ octopus --version
unknown flag: --version

Expectation from CLI users like me: all CLIs support a --help and a --version flag, as the old client did

Unable to manage variables stored in config-as-code source repo

The bug

None of the project variable subcommands allow managing variables stored in configuration (Config-as-code).

Command to reproduce

The affected commands are:

octopus project variable list
octopus project variable view
octopus project variable create
octopus project variable update

Outcome

The create command will only create variables in the database, they will still be associated with the project, but they will not be visible in the source repo.
The update command will not be able to find the variables stored in the source repo.
The update command will not be able to find the variables stored in the source repo.
The list command will only show variable stored in the database, not any stored in the source repo.

Versions

cli: 1.1.0

Octopus Server: any that support Config-as-code

Links

Add commands for Runbook operations, specifically 'create-runbook'

Good morning,

Can I please request that you add additional commands for Runbook operations to the Octopus CLI.

Presently the only Runbook operation in is run-runbook. What I'd like to see are these two operations -

  • create-runbook: Ideally this would work in almost exactly the same way as create-release, allowing the specification of defaultPackageVersion and package to set package versions to use with steps. I'd also like to be able to optionally publish the new Runbook after creation.
  • publish-runbook: This operation would allow publishing of an existing Runbook.

Assuming I have one or more steps in both my Deployment Process and a Runbook that references a script, currently when using AWS CodeBuild I can create a package, upload it to S3 and then create a release on Octopus, but I have to manually create the Runbook and then publish it. What I'd like to be able to do is something like this.

version: 0.2
env:
  shell: bash
phases:
  ...
  build:
    commands:
      - dotnet-octo pack --id="${PACKAGE_ID}" --basePath="${PACKAGE_BASE_PATH}" --version=${VERSION} --outFolder=Artifacts --format=zip
      - aws s3 cp Artifacts/${PACKAGE_ID}.*.zip ${BUCKET_FEED_URL}
      - dotnet-octo create-release --project ${PROJECT_ID} --space ${SPACE_ID} --defaultPackageVersion ${VERSION} --version ${VERSION} --ignoreExisting
      - dotnet-octo create-runbook --project ${PROJECT_ID} --space ${SPACE_ID} --defaultPackageVersion ${VERSION} --name ${VERSION} --ignoreExisting --publish

I'd be happy to provide further details if that would help.

Thanks.
David

Runbook List Nil Pointer Error

The bug

Error when attempting to list available runbooks in a Project.

Command to reproduce

Identical error when specifying the Space or Project or using interactively

octopus -s SpaceName runbook list --project 'Project Name'
octopus -s SpaceName runbook list 
octopus runbook list

Outcome

panic: runtime error: invalid memory address or nil pointer dereference
[signal 0xc0000005 code=0x0 addr=0x0 pc=0xdfca65]

goroutine 1 [running]:
github.com/OctopusDeploy/cli/pkg/cmd/runbook/list.listRun(0xc000476900, {0x10bf448?, 0xc0003dc3c0}, 0xc000008798)
        /home/runner/work/cli/cli/pkg/cmd/runbook/list/list.go:120 +0x465
github.com/OctopusDeploy/cli/pkg/cmd/runbook/list.NewCmdList.func1(0xc000476900?, {0xc000096a00?, 0x2?, 0x2?})
        /home/runner/work/cli/cli/pkg/cmd/runbook/list/list.go:57 +0x73
github.com/spf13/cobra.(*Command).execute(0xc000476900, {0xc0000969e0, 0x2, 0x2})
        /home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:916 +0x862
github.com/spf13/cobra.(*Command).ExecuteC(0xc00039ac00)
        /home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:1044 +0x3bd
github.com/spf13/cobra.(*Command).Execute(...)
        /home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:968
main.main()
        /home/runner/work/cli/cli/cmd/octopus/main.go:73 +0x465

Versions

cli:1.3.0

Octopus Server:2021.1.7665

Links

Update README

The README should include the following sections:

  • Project Overview
  • Supported Commands
  • Environment Variables
  • Contribution Guidelines (i.e. Build Instructions)

`config set` command writes more than it should

Repro on both Windows and Linux

Set OCTOPUS_HOST and OCTOPUS_API_KEY environment variables to allow you to connect to your server.

Make sure you don't have any pre-existing CLI config file by deleting the file %APPDATA%\octopus\cli_config.json

Run octopus config set space default (or any other thing that would write a config value)

The CLI will re-generate the config file; open it and inspect the contents

Expected:
config file contains only values that I have explicitly put there using config set

{
  "space": "Default"
}

Observed:
config file contains all entries, including values picked up from the environment. On my system, it looked like this

{
  "apikey": "API-<redacted>",
  "editor": "notepad",
  "host": "http://localhost:8050",
  "noprompt": false,
  "outputformat": "table",
  "space": "Default"
}

No way to view deployment progress

Does the CLI have an equivalent of the --progress command in the old cli which showed the output of the task log while deployment was occuring?

Proxy support for CLI

This is a reminder task for us to officially support HTTP(s) proxies for the CLI. This may involve some configuration (e.g. OCTOPUS_PROXY environment variables or command line switches) and testing.

Things to consider (we may choose not to support all of these):

  • Authenticated proxies (PROXY_USERNAME, PROXY_PASSWORD)
  • Windows/NTLM authentication. Perhaps not something that is achievable?
  • Test matrix? Will running an integration test against squid in a docker container be sufficient or do we need to test others too?
  • SOCKS proxies or just HTTPS?

runbook-run subcommand

OctopusDeploy/OctopusCLI#243

We are considering adding a set of commands that will allow users to list, view, and delete runs of runbooks. This is done to perform administrative operations against Octopus. Unfortunately, this request poses a naming challenge; how do we represent runbook runs? A runbook run is a historical artefact in the context of Octopus. However, it's also refers to an action associated with a runbook (i.e. "the runbook ran to update the server"). It's confusing.

I propose the establishment of a runbook-run subcommand:

$ octopus runbook-run [command]

This subcommand would allow you to delete, list, and view runbook runs; runbooks that executed in the past.

In summary, the revised list of runbook-related commands would be:

$ octopus runbook delete       # deletes a runbook
$ octopus runbook execute      # executes a runbook
$ octopus runbook list         # lists runbooks
$ octopus runbook-run delete   # deletes a runbook run
$ octopus runbook-run list     # lists runbook runs
$ octopus runbook-run view     # views a runbook run
$ octopus runbook view         # view a runbook

`tenant create` and `tenant view` commands are not providing json output

The bug

tenant create and tenant view are not providing JSON output when the -f json flag is supplied.

Command to reproduce

tenant view "tenant name" -f json

Outcome

octopus tenant view "tenant 99"  --space tenants -f json
tenant 99 (Tenants-321)
No description provided

Versions

cli: all that support tenant create and view commnands

Octopus Server: all supported

Workaround

tenant list -f json will provide json output for all tenants, allowing for client side filtering

Links

Error message for executing commands against 2022.2 or earlier is unhelpful

The bug

Running commands that rely on the executions API (version 2022.3+) will result in an unhelpful error message.

Command to reproduce

This can affect the following commands when run against a version earlier than 2022.3:
release create
release deploy
runbook run

Outcome

See issue #217 which describes the error

Versions

cli: any

Octopus Server:2022.2 or earlier

Links

#217

`octopus project view` and some other project-related commands send spurious `clonedFromProjectId` query string parameter.

@geofflamrock found this while experimenting with the CLI and doing

octopus project view "Example"

He received an error

octopus deploy api returned an error on endpoint /api/Spaces-1/projects?clonedFromProjectId=&partialName=Example

The actual exception was caused by the migration of that endpoint away from Nancy and is not the fault of the CLI:

When it was implemented in nancy, it would see clonedFromProjectId=, but then use string.IsNullOrEmpty to ignore the empty value.
When the endpoint was migrated, the IsNullOrEmpty check was replaced with a simple null check, causing a query on empty string to be generated.


The nancy group will fix the server, but nevertheless, the CLI shouldn't be sending this empty clonedFromProjectId= query parameter in the first place. As above we can see it on project view; I'm pretty sure it occurs during release creation and other places that look up projects, so may perhaps exist in https://github.com/OctopusDeploy/go-octopusdeploy

Problems with git credentials creating new VCS backed project

The bug

I'm attempting to create a new project in Octopus via the cli. I'm using an existing git credential stored in the library. When I run the command without the --git-credential-store argument I'm prompted for this information, even though the docs state "Library" is the default. When I supply --git-credential-store "Library" I'm prompted for the git username, which I shouldn't need to supply since it should be coming from the library value. It seems like perhaps it's trying to create an new library value. I want to utilize an existing library credential.

Command to reproduce

octopus project create --process-vcs -n ${PWD##*/} -l <lifecycle_name> -g "Default Project Group" --git-url $(git config --get remote.origin.url) --git-credentials <library_credential_name> --git-credential-store "Library" -s Default

Outcome

? The Git username.
? Git username 

Versions

cli: 1.2.0
P.S. you should add a version flag

Octopus Server: 2023.1.8263-hotfix.8481

Links

Create Release --package=VALUE - Unable to include `/` in package name in value

The bug

When running the create-release command, the package version isn't able to include a package name with a /

A workaround is to use --packageVersion to set the default package version, however this isn't suitable for deployments that reference other packages without manually including version for each of the referenced packages.

Alternatively using the format StepName:Version or an asterisk can be used.

Both StepName:PackageName:Version and PackageID:Version are effected by this:

      --package=VALUE        [Optional] Version number to use for a package
                             in the release. Format: StepName:Version or
                             PackageID:Version or
                             StepName:PackageName:Version. StepName,
                             PackageID, and PackageName can be replaced with
                             an asterisk. An asterisk will be assumed for
                             StepName, PackageID, or PackageName if they are
                             omitted. 

Command to reproduce

  1. Configure an Octopus Project to deploy a package that includes a / in it's name (e.g. a docker container)
  2. Run a create release command that specifies the version for the package:
octo create-release --project myProject --version 0.0.1 --package "octopusdeploy/tentacle:5.2.0-ubuntu.22.04"
octo create-release --project myProject --version 0.0.1 --package "Run a Script:octopusdeploy/tentacle:5.2.0-ubuntu.22.04"

Outcome

The following line is logged:

The package version for some steps was not specified. Going to try and resolve those automatically...

And the latest package version used instead of the version specified.

Versions

cli: Octopus CLI, version 9.1.7

Octopus Server: 2023.4.4798

Links

Internal Link - Zendesk
Internal Link - Slack

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.