Skip to content

Latest commit

 

History

History
320 lines (259 loc) · 13.9 KB

DOCS.md

File metadata and controls

320 lines (259 loc) · 13.9 KB

Description

This plugin enables you to manage artifacts in Artifactory in a Vela pipeline.

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

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

Usage

NOTE:

Users should refrain from using latest as the tag for the Docker image.

It is recommended to use a semantically versioned tag instead.

Sample of copying an artifact:

steps:
  - name: copy_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: copy
      path: libs-snapshot-local/foo.txt
      target: libs-snapshot-local/bar.txt
      url: http://localhost:8081/artifactory

Sample of deleting an artifact:

steps:
  - name: delete_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: delete
      path: libs-snapshot-local/foo.txt
      url: http://localhost:8081/artifactory

Sample of setting properties on an artifact:

steps:
  - name: set_properties_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: set-prop
      path: libs-snapshot-local/foo.txt
      props:
        - name: single
          value: foo
        - name: multiple
          values:
            - bar
            - baz
      url: http://localhost:8081/artifactory

Sample of uploading an artifact:

steps:
  - name: upload_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: upload
      path: libs-snapshot-local/
      sources:
        - foo.txt
        - target/*.jar
        - dist/**/*.js
      url: http://localhost:8081/artifactory

Sample of uploading an artifact using regexp:

steps:
  - name: upload_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: upload
      path: libs-snapshot-local/
      regexp: true
      sources:
        - dist/([a-z]+).js
      url: http://localhost:8081/artifactory

Important

As the JFrog docs call out: If you have specified that you are using regular expressions, then the beginning of the expression must be enclosed in parenthesis. For example: a/b/c/(.*)/file.zip

Sample of uploading an artifact using build props (matrix parameters):

steps:
  - name: upload_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: upload
      path: libs-snapshot-local/file
      sources:
        - file.txt
      build_props: build.name=buildName;build.number=17;build.timestamp=1600856623553
      url: http://localhost:8081/artifactory

Sample of pretending to upload an artifact:

steps:
  - name: upload_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: upload
+     dry_run: true
      path: libs-snapshot-local/
      sources:
        - foo.txt
        - target/*.jar
        - dist/**/*.js
      url: http://localhost:8081/artifactory

Sample of using docker-promote on an artifact:

steps:
  - name: docker_promote_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: docker-promote
      target_repo: libs-snapshot-local
      docker_registry: octocat/hello-world
      tag: latest
      target_docker_registry: octocat/hello-world
      target_tags: "${VELA_BUILD_COMMIT:0:8}"

Secrets

NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.

Internal

The plugin accepts the following parameters for authentication:

Parameter Environment Variable Configuration
api_key PARAMETER_API_KEY, ARTIFACTORY_API_KEY
password PARAMETER_PASSWORD, ARTIFACTORY_PASSWORD
username PARAMETER_USERNAME, ARTIFACTORY_USERNAME

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: copy_artifacts
    image: target/vela-artifactory:latest
    pull: always
+   secrets: [ artifactory_username, artifactory_password ]
    parameters:
      action: copy
      path: libs-snapshot-local/foo.txt
      target: libs-snapshot-local/bar.txt
      url: http://localhost:8081/artifactory
-     username: octocat
-     password: superSecretPassword

This example will add the secrets to the copy_artifacts step as environment variables:

  • ARTIFACTORY_USERNAME=<value>
  • ARTIFACTORY_PASSWORD=<value>

External

The plugin accepts the following files for authentication:

Parameter File Configuration
api_key /vela/parameters/artifactory/api_key, /vela/secrets/artifactory/api_key, /vela/secrets/managed-auth/api_key
password /vela/parameters/artifactory/password, /vela/secrets/artifactory/password, /vela/secrets/managed-auth/password
username /vela/parameters/artifactory/username, /vela/secrets/artifactory/username, /vela/secrets/managed-auth/username

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: copy_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: copy
      path: libs-snapshot-local/foo.txt
      target: libs-snapshot-local/bar.txt
      url: http://localhost:8081/artifactory
-     username: octocat
-     password: superSecretPassword

This example will read the secret values in the build workspace stored at /vela/secrets/artifactory/*

Parameters

NOTE:

The plugin supports reading all parameters via:

  • environment variables - PARAMETER_* OR ARTIFACTORY_*
  • files - /vela/parameters/artifactory/* OR /vela/secrets/artifactory/*

Any values set from a file takes precedence over values set from the environment.

The following parameters are used to configure the image:

Name Description Required Default Environment Variables
action action to perform against Artifactory true N/A PARAMETER_ACTION
ARTIFACTORY_ACTION
api_key API key for communication with Artifactory false N/A PARAMETER_API_KEY
ARTIFACTORY_API_KEY
dry_run enables pretending to perform the action false false PARAMETER_DRY_RUN
ARTIFACTORY_DRY_RUN
log_level set the log level for the plugin true info PARAMETER_LOG_LEVEL
ARTIFACTORY_LOG_LEVEL
password password for communication with Artifactory false N/A PARAMETER_PASSWORD
ARTIFACTORY_PASSWORD
url Artifactory instance to communicate with true N/A PARAMETER_URL
ARTIFACTORY_URL
username user name for communication with Artifactory false N/A PARAMETER_USERNAME
ARTIFACTORY_USERNAME
http_client_retries number of times to retry failed http attempts false 3 PARAMETER_HTTP_CLIENT_RETRIES
ARTIFACTORY_HTTP_CLIENT_RETRIES
http_client_retry_wait amount of milliseconds to wait between failed http attempts false 500 PARAMETER_HTTP_CLIENT_RETRY_WAIT_MILLISECONDS
ARTIFACTORY_HTTP_CLIENT_RETRY_WAIT_MILLISECONDS
http_client_cert file path to the client certificate to use for TLS communication false N/A PARAMETER_HTTP_CLIENT_CERT
ARTIFACTORY_HTTP_CLIENT_CERT
http_client_cert_key file path to the client certificate key to use for TLS communication false N/A PARAMETER_HTTP_CLIENT_CERT_KEY
ARTIFACTORY_HTTP_CLIENT_CERT_KEY
http_client_insecure_tls enable insecure TLS communication false false PARAMETER_HTTP_CLIENT_INSECURE_TLS
ARTIFACTORY_HTTP_CLIENT_INSECURE_TLS

Copy

The following parameters are used to configure the copy action:

Name Description Required Default Environment Variables
flat enables removing source directory hierarchy false false PARAMETER_FLAT
ARTIFACTORY_FLAT
path source path to copy artifact(s) from true N/A PARAMETER_PATH
ARTIFACTORY_PATH
recursive enables copying sub-directories for the artifact(s) false false PARAMETER_RECURSIVE
ARTIFACTORY_RECURSIVE
target target path to copy artifact(s) to true N/A PARAMETER_TARGET
ARTIFACTORY_TARGET

Delete

The following parameters are used to configure the delete action:

Name Description Required Default Environment Variables
path target path to delete artifact(s) from true N/A PARAMETER_PATH
ARTIFACTORY_PATH
recursive enables removing sub-directories for the artifact(s) false false PARAMETER_RECURSIVE
ARTIFACTORY_RECURSIVE

Docker-Promote

The following parameters are used to configure the docker-promote action:

Name Description Required Default Environment Variables
copy set to copy instead of moving the image false true PARAMETER_COPY
ARTIFACTORY_COPY
docker_registry path to image in docker registry true N/A PARAMETER_DOCKER_REGISTRY
ARTIFACTORY_DOCKER_REGISTRY
promote_props enables setting properties on the promoted artifact false false PARAMETER_PROMOTE_PROPS
ARTIFACTORY_PROMOTE_PROPS
tag name of the tag for promoting true N/A PARAMETER_TAG
ARTIFACTORY_TAG
target_docker_registry path for target image in docker registry true N/A PARAMETER_TARGET_DOCKER_REGISTRY
ARTIFACTORY_TARGET_DOCKER_REGISTRY
target_repo name of the docker registry containing the image true N/A PARAMETER_TARGET_REPO
ARTIFACTORY_TARGET_REPO
target_tags name of the final tags after promotion true N/A PARAMETER_TARGET_TAGS
ARTIFACTORY_TARGET_TAGS

Set-Prop

The following parameters are used to configure the set-prop action:

Name Description Required Default Environment Variables
path target path to artifact(s) true N/A PARAMETER_PATH
ARTIFACTORY_PATH
props properties to set on the artifact(s) true N/A PARAMETER_PROPS
ARTIFACTORY_PROPS

Upload

The following parameters are used to configure the upload action:

Name Description Required Default Environment Variables
build_props build props (matrix parameters) to apply false N/A PARAMETER_BUILD_PROPS
ARTIFACTORY_BUILD_PROPS
flat enables removing source directory hierarchy false false PARAMETER_FLAT
ARTIFACTORY_FLAT
include_dirs enables including sub-directories for the artifact(s) false false PARAMETER_INCLUDE_DIRS
ARTIFACTORY_INCLUDE_DIRS
path target path to upload artifact(s) to true N/A PARAMETER_PATH
ARTIFACTORY_PATH
recursive enables uploading sub-directories for the artifact(s) false false PARAMETER_RECURSIVE
ARTIFACTORY_RECURSIVE
regexp enables reading the sources as a regular expression false false PARAMETER_REGEXP
ARTIFACTORY_REGEXP
sources list of artifact(s) to upload true N/A PARAMETER_SOURCES
ARTIFACTORY_SOURCES

Template

COMING SOON!

Troubleshooting

You can start troubleshooting this plugin by tuning the level of logs being displayed:

steps:
  - name: copy_artifacts
    image: target/vela-artifactory:latest
    pull: always
    parameters:
      action: copy
+     log_level: trace
      path: libs-snapshot-local/foo.txt
      target: libs-snapshot-local/bar.txt
      url: http://localhost:8081/artifactory

Below are a list of common problems and how to solve them: