SCP

Description

This plugin is part of the OpenSSH suite of plugins which enables you to use the scp binary in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-openssh

Registry: https://hub.docker.com/r/target/vela-scp

Usage

Because the plugin is a thin wrapper around the scp binary, the syntax and parameters follow from the OpenSSH manual. The plugin will take care of some basic secrets identity management tasks for you, most importantly is that when an identity file is provided as a secret the plugin will place the file into the filesystem and change the permissions to match what the binary expects, and then add it to the list of identity files tried as part of authentication. Additionally, if using a password or passphrase for authentication or for unlocking an identity file, the sshpass binary will be used to provide those credentials without interactive user input.

NOTE:
Users should refrain from using latest as the tag for images.
It is recommended to use a semantically versioned tag instead.

Basic usage

steps:
  - name: scp basic usage
    image: target/vela-scp:latest
    pull: always
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
        - a_user_name@some_remote_host_name:/absolute/path/on/remote/system
      target: a_different_user@some_other_host:~

Using the `scp://` schema for non-standard ports

steps:
  - name: scp to non-standard port
    image: target/vela-scp:latest
    pull: always
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
        - a_user_name@some_remote_host_name:/absolute/path/on/remote/system
+     target: scp://a_different_user@some_remote_host_name:12345/path

Passing additional `scp` flags

steps:
  - name: override default scp flags
    image: target/vela-scp:latest
    pull: always
    parameters:
      source:
        - ./relative/path/to/folder/in/vela/workspace
      target: scp://a_different_user@some_remote_host_name:12345/path
+     scp_flag:
+       - "-r"
+       - "-o StrictHostKeyChecking=yes"

Using a password for authentication

steps:
  - name: password for authentication
    image: target/vela-scp:latest
    pull: always
+   secrets:
+     - source: my_non_user_account_password
+       target: sshpass_password
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
      target: scp://a_different_user@some_remote_host_name:12345/path

Using an identity file (WITHOUT a passphrase) from an internal secret

steps:
  - name: identity file contents from an internal secret
    image: target/vela-scp:latest
    pull: always
+   secrets:
+     - source: my_non_user_account_id_rsa_file_contents
+       target: identity_file_contents
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
      target: scp://a_different_user@some_remote_host_name:12345/path

Using an identity file (WITH a passphrase) from an internal secret

steps:
  - name: identity file contents with passphrase from an internal secret
    image: target/vela-scp:latest
    pull: always
+   secrets:
+     - source: my_non_user_account_id_rsa_file_contents
+       target: identity_file_contents
+     - source: my_non_user_account_id_rsa_passphrase
+       target: sshpass_passphrase
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
      target: scp://a_different_user@some_remote_host_name:12345/path

Using an existing identity file from the workspace

steps:
  - name: identity file from the workspace
    image: target/vela-scp:latest
    pull: always
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
      target: scp://a_different_user@some_remote_host_name:12345/path
+     identity_file_path: ./some/workspace/location/id_rsa

Using additional secrets in other parameters

steps:
  - name: additional secrets in other parameters
    image: target/vela-scp:latest
    pull: always
+   secrets:
+     - source: some_secret_user
+       target: secret_user
+     - source: some_secret_host
+       target: secret_host
+     - source: some_secret_port
+       target: secret_port
    parameters:
      source:
        - ./relative/path/to/file/in/vela/workspace
+     target: scp://$SECRET_USER@$SECRET_HOST:$SECRET_PORT/path

Using the container without the plugin logic

steps:
  - name: override plugin logic to use scp directly
    image: target/vela-scp:latest
    pull: always
+   commands:
+     - scp -i ./some/existing/id_rsa ./relative/path/to/file/in/vela/workspace username@hostname:/path/

Parameters & Secrets

NOTE:
The plugin supports reading all parameters via environment variables or files.
Any values set from a file take precedence over values set from the environment.
Don’t confuse the source/target syntax of native secrets with the source and target parameters required for the scp binary.

Name	Description	Required	Accepts Multiple Values?	Default	Environment Variables	File Paths
`source`	The source option from the `scp` manual.	✅	✅		`PARAMETER_SOURCE` `SOURCE`	`/vela/parameters/vela-scp/source` `/vela/secrets/vela-scp/source`
`target`	The target option from the `scp` manual.	✅	❌		`PARAMETER_TARGET` `TARGET`	`/vela/parameters/vela-scp/target` `/vela/secrets/vela-scp/target`
`identity_file_path`	A path for where the `scp` binary should look for existing identity files. These are NOT auto created by the plugin as they must be created and managed by a user and only referenced here.	❌	✅		`PARAMETER_IDENTITY_FILE_PATH` `IDENTITY_FILE_PATH` `PARAMETER_SSH_KEY_PATH` `SSH_KEY_PATH`	`/vela/parameters/vela-scp/identity-file.path` `/vela/secrets/vela-scp/identity-file.path`
`identity_file_contents`	The raw contents of an identity file for use with `scp`. The plugin will take the raw contents and place it in a temporary location in the workspace with the correct permissions and inject it as an identity file to use during execution.	❌	❌		`PARAMETER_IDENTITY_FILE_CONTENTS` `IDENTITY_FILE_CONTENTS` `PARAMETER_SSH_KEY` `SSH_KEY`	`/vela/parameters/vela-scp/identity-file.contents` `/vela/secrets/vela-scp/identity-file.contents`
`scp_flag`	Any additional options from the `scp` manual. These will override the default options and be placed between the identity file options and the source/target options at the end.	❌	✅	`-o StrictHostKeyChecking=no` `-o UserKnownHostsFile=/dev/null`	`PARAMETER_SCP_FLAG` `SCP_FLAG`	`/vela/parameters/vela-scp/scp.flag` `/vela/secrets/vela-scp/scp.flag`
`sshpass_password`	If any systems require a password for authentication it can be specified here, and the `sshpass` binary will be used in conjunction with `scp`.	❌	❌		`PARAMETER_SSHPASS_PASSWORD` `PARAMETER_PASSWORD` `SSHPASS_PASSWORD` `PASSWORD`	`/vela/parameters/vela-scp/sshpass.password` `/vela/secrets/vela-scp/sshpass.password`
`sshpass_passphrase`	If any identity files require a passphrase for authentication it can be specified here, and the `sshpass` binary will be used in conjunction with `scp`.	❌	❌		`PARAMETER_SSHPASS_PASSPHRASE` `SSHPASS_PASSPHRASE`	`/vela/parameters/vela-scp/sshpass.passphrase` `/vela/secrets/vela-scp/sshpass.passphrase`
`sshpass_flag`	Any additional options from the `sshpass` manual.	❌	✅		`PARAMETER_SSHPASS_FLAG` `SSHPASS_FLAG`	`/vela/parameters/vela-scp/sshpass.flag` `/vela/secrets/vela-scp/sshpass.flag`

Last modified March 8, 2022: feat(openssh): Add SSH & SCP documentation (#287) (fe29de8f)

SCP