Skip to content

DOCS.md

Latest commit

 

History

History
189 lines (149 loc) · 7.37 KB

DOCS.md

File metadata and controls

189 lines (149 loc) · 7.37 KB

Description

NOTE: This plugin is automatically injected into your pipeline for the source repository.

This plugin enables you to clone repositories in a Vela pipeline to your build workspace.

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

Registry:

vela-git-slim contains basic packages required to perform basic git operations - ideal for regular clone steps.

vela-git contains all of vela-git-slim and additional utility packages related to git, such as git-lfs and gh (GitHub CLI).

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 cloning a repository:

steps:
  - name: clone_vela-git-test
    image: target/vela-git-slim:latest
    pull: always
    parameters:
      path: vela-git-test
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682

Sample of cloning a repository with submodules:

steps:
  - name: clone_vela-git-test
    image: target/vela-git-slim:latest
    pull: always
    parameters:
      path: vela-git-test
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682
+     submodules: true

Sample of cloning a repository with tags:

steps:
  - name: clone_vela-git-test
    image: target/vela-git-slim:latest
    pull: always
    parameters:
      path: vela-git-test
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682
+     tags: true

Sample of cloning a repository and resolving LFS objects with the vela-git plugin:

steps:
  - name: clone_vela-git-test
    image: target/vela-git:latest
    pull: always
    parameters:
      path: vela-git-test
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682
+     lfs: true

Secrets

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

Internal

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

steps:
  - name: clone_vela-git-test
    image: target/vela-git-slim:latest
    pull: always
+   secrets: [ git_username, git_password ]
    parameters:
-     username: octocat
-     password: superSecretPassword
      path: /home/go-vela_vela-git-test_1
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682

This example will add the secrets to the clone_vela-git-test step as environment variables:

  • GIT_USERNAME=<value>
  • GIT_PASSWORD=<value>

External

The plugin accepts the following files for authentication:

Parameter Volume Configuration
password /vela/parameters/git/password, /vela/secrets/git/password
username /vela/parameters/git/username, /vela/secrets/git/username

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

steps:
  - name: clone_vela-git-test
    image: target/vela-git-slim:latest
    pull: always
    parameters:
-     username: octocat
-     password: superSecretPassword
      path: /home/go-vela_vela-git-test_1
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682

This example will read the secret values in the volume stored at /vela/secrets/

Parameters

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.

The following parameters are used to configure the image:

Name Description Required Default Environment Variables
branch initial branch to clone from repository true master PARAMETER_BRANCH
GIT_BRANCH
VELA_PULL_REQUEST_SOURCE
VELA_BUILD_BRANCH
log_level set the log level for the plugin true info PARAMETER_LOG_LEVEL
GIT_LOG_LEVEL
machine machine name to communicate with true github.com PARAMETER_MACHINE
GIT_MACHINE
VELA_NETRC_MACHINE
password password for authentication true set by Vela PARAMETER_PASSWORD
GIT_PASSWORD
VELA_NETRC_PASSWORD
username user name for authentication true set by Vela PARAMETER_USERNAME
GIT_USERNAME
VELA_NETRC_USERNAME
path local path to clone repository to true set by Vela PARAMETER_PATH
GIT_PATH
VELA_BUILD_WORKSPACE
ref reference generated for commit true refs/heads/master PARAMETER_REF
GIT_REF
VELA_BUILD_REF
remote full url for cloning repository true set by Vela PARAMETER_REMOTE
GIT_REMOTE
VELA_REPO_CLONE
sha SHA-1 hash generated for commit true set by Vela PARAMETER_SHA
GIT_SHA
VELA_BUILD_COMMIT
submodules enables fetching of submodules false false PARAMETER_SUBMODULES
GIT_SUBMODULES
tags enables fetching of tags false false PARAMETER_TAGS
GIT_TAGS
depth enables fetching with a specific depth false 100 PARAMETER_DEPTH
GIT_DEPTH
lfs1 enables resolving LFS objects false false PARAMETER_LFS
GIT_LFS

Template

COMING SOON!

Troubleshooting

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

steps:
  - name: clone_vela-git-test
    image: target/vela-git-slim:latest
    pull: always
    parameters:
+     log_level: trace
      path: vela-git-test
      ref: refs/heads/main
      remote: https://github.com/go-vela/vela-git-test.git
      sha: ee1e671529ad86a11ed628a04b37829e71783682

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

Footnotes

  1. only functional in the target/vela-git plugin. ↩