Upload and Download Artifacts in a Nexus Raw Repository
Pipelines that exchange binaries, tarballs, documentation bundles, or test reports with Nexus often need to upload to or download from a hosted raw repository rather than use a Maven, npm, or PyPI package format. Without a Connector, this means a pipeline author has to:
- Find the exact Nexus raw repository name and, for downloads, the complete
file path in the Nexus console, then paste them into the
TaskRun. - Create and maintain a
kubernetes.io/basic-authSecret in the user namespace, carrying the long-lived username and password. - Re-create that Secret in every namespace that uses Nexus, and rotate it everywhere whenever the Nexus credential changes.
This guide shows the alternative path: reference a platform Nexus
Connector through the nexus-raw-repository ResourceInterface, and let
the connectors CSI driver inject the proxy URL and CA certificate at
TaskRun time. The user namespace never stores a plaintext Nexus Secret,
and credential rotation is transparent.
A ResourceInterface (RI) is a reusable Connector-to-Task binding
template. The platform ships nexus-raw-repository to map a Nexus Connector,
a selected raw repository, and an optional file path onto the inputs that raw
upload and download Tasks expect.
TOC
What Problem This SolvesBefore You BeginPrerequisitesHow the Connector Path DiffersStep 1 — Create the Nexus ConnectorStep 2 — Upload with the ResourceInterfaceStep 3 — Verify the UploadStep 4 — Select and Download a Raw FileStep 5 — Verify the DownloadCredential RotationTroubleshooting401 Unauthorized from Nexus403 Forbidden on uploadFile selector returns no options403 Forbidden on a dropdown queryDownload fails because the path was not foundsourcePath must not be absolutePod stuck in ContainerCreatingx509: certificate signed by unknown authorityReferenceWhat Problem This Solves
Use this approach when you need to:
- Upload artifacts to a hosted raw repository from a Tekton
TaskRun(single file, directory tree, glob expansion, optional packaging into a tarball, optionalsha256checksum manifest — all capabilities shipped by thenexus-uploadTekton Task that comes with the platform). - Download an existing raw artifact by selecting its complete path instead of copying the path from the Nexus console.
- Drop hand-managed Secrets in user namespaces and let the platform Connector own the credential lifecycle.
- Pick the repository from a list filtered to
rawformat andhostedtype, then search its files when configuring a download.
Before You Begin
Prerequisites
Examples below assume the default install namespace
connectors-system. If your platform installs the Connectors component into a different namespace, substitute that namespace where you seeconnectors-system.
- Tekton Pipelines is installed.
- The Connectors system and the Nexus Connector component are
installed (
ConnectorsCoreandConnectorsNexusCRs reconciled Ready). - The
nexus-uploadornexus-downloadTekton Task is installed in the namespace where you will run theTaskRun. The Task must be on a version that consumes thenexus-raw-repositoryResourceInterface. Refer to the platform release notes for the Task version that introduces Connector support. - A Nexus Connector pointing at the target Nexus instance, with a Secret that holds a Nexus user with read permission for downloads and read and write permission for uploads on the selected hosted raw repository.
- The target raw repository already exists in Nexus. This guide does not provision repositories — see Nexus Connector Automatic Creation for that flow.
How the Connector Path Differs
Uploads use HTTP PUT and downloads use HTTP GET on
<address>/repository/<repo>/<path>. The Connector path changes how curl
authenticates: instead of seeing the Nexus user, it sees the forward-proxy URL,
and the proxy authenticates the upstream connection using the Connector's
stored credentials.
Step 1 — Create the Nexus Connector
If you already have a Nexus Connector for mvn, npm, or pypi
workflows, the same Connector also serves raw uploads and downloads — skip to
Step 2.
Wait until the Connector reports Ready=True:
Step 2 — Upload with the ResourceInterface
The nexus-upload Task declares an auth workspace and a repository
parameter, both of which the nexus-raw-repository ResourceInterface maps in
the Pipeline editor. The following hand-written TaskRun shows the equivalent
runtime binding after that editor-time mapping. It references the Connector
directly because a TaskRun does not reference a ResourceInterface object:
When the pod starts, the CSI driver writes two files into the auth
workspace:
.env— exportsHTTPS_PROXY,HTTP_PROXY,https_proxy,http_proxy,no_proxy, all pointing at the platform forward proxy. The proxy URL embeds short-lived credentials derived from the Connector identity and the TaskRun ServiceAccount token.ca.crt— the CA bundle that signs the forward proxy's TLS certificate.
The Task internally sources .env to pick up HTTPS_PROXY, then runs
curl -X PUT --cacert <auth_workspace>/ca.crt --upload-file <file> <address>/repository/<repository>/<path>. The forward proxy validates
the TaskRun-scoped credential, looks up the Nexus Connector, swaps the
proxy auth for the Connector's real Nexus username and password, and
forwards the PUT to Nexus.
Step 3 — Verify the Upload
After the TaskRun succeeds:
- List
results on theTaskRun—nexus-uploadexposes a result per uploaded file containing the final absolute URL. - Open one of the URLs from the previous step. Nexus should return the artifact unchanged.
- Check the Nexus console under Browse → Components for the target raw repository to confirm the upload appeared there.
Step 4 — Select and Download a Raw File
In the Pipeline editor, add a Pipeline Integration based on the
nexus-raw-repository ResourceInterface, then:
- Select the Nexus Connector.
- Select a repository. The list contains only repositories whose Nexus format
is
rawand whose type ishosted. - Select File Path. The form calls the Nexus asset search API for the selected repository and displays each file's complete path.
- To narrow a large first page, enter text in the file selector's search box.
The form sends the text to Nexus as the
qquery parameter. Nexus applies its own full-text search semantics; this is not guaranteed to be a simple file-namecontainsmatch.
Raw repositories do not assign Maven-style versions to files. The selected value is the complete repository-relative path, for example:
Some Nexus versions return the same path with a leading /. The
ResourceInterface removes that leading slash before passing the value to the
Task because nexus-download expects a repository-relative sourcePath, not
an absolute path or download URL.
Map the Integration to the nexus-download Task as follows:
The Pipeline editor can recommend these mappings when the Task declares its
RawRepository Integration contract. You can also select each Integration
attribute manually. The path parameter is optional with an empty default, so
Pipeline Integrations saved before file selection was introduced remain
loadable.
The selector currently exposes the first page returned by Nexus and does not
automatically load continuation pages. A valid repository with no matching
files returns a successful response with an empty items array; it is not an
authentication or system error.
Step 5 — Verify the Download
After the TaskRun succeeds:
- Confirm that the Task received a repository-relative
sourcePathwithout a leading slash. - Check the Task result or output workspace for the downloaded file.
- Compare its checksum or contents with the source asset in Nexus.
Credential Rotation
To rotate the Nexus user password used by all TaskRuns of all
namespaces that reference this Connector:
Future TaskRuns pick up the new credential automatically. There is
no need to redeploy pipelines or edit user-namespace Secrets — those
Secrets do not exist on this path.
Troubleshooting
401 Unauthorized from Nexus
The Connector's Secret contains missing or invalid Nexus credentials. Correct
the username or password and wait for the Connector to return to Ready=True.
403 Forbidden on upload
The Connector's Nexus user is valid but does not have write permission on the
target raw repository. Adjust the Nexus user's role to include
nx-repository-view-raw-<repo>-add and
nx-repository-view-raw-<repo>-edit, then retry.
File selector returns no options
An empty selector is a valid result when the repository is empty or the search text matches no asset. Clear the search text and retry. If files are still missing, verify that the Connector's Nexus user has browse and read permission for the repository.
403 Forbidden on a dropdown query
First check the platform permission of the user currently configuring the
Pipeline Integration. That user must have get on
connectors/apis/nexus/service/rest/v1/repositories and
connectors/apis/nexus/service/rest/v1/search/assets. Grant the user a
platform role that aggregates cpaas:connectors-nexus-apis:view or higher in
the namespace.
If the platform permission is present, the upstream Nexus account may lack browse or read permission for the selected repository. Update that account's Nexus role and retry.
Download fails because the path was not found
The selected asset may have been deleted or moved after the Pipeline
Integration was saved. Open the file selector again and choose a current path.
The list API can return an empty successful response for no matches, while the
subsequent download of a specific missing path fails with Nexus HTTP 404
semantics.
sourcePath must not be absolute
Do not add / before the selected path. Re-open and save the Pipeline
Integration so the ResourceInterface can normalize the Nexus path, or enter a
repository-relative value such as releases/app/v1/package.tar.gz.
Pod stuck in ContainerCreating
The CSI driver is reporting a mount error. kubectl describe pod will
show the underlying message — common causes are a wrong
volumeAttributes.connectors namespace/name, a Connector that has
never reached Ready=True, or an unbound auth workspace in the
TaskRun.
x509: certificate signed by unknown authority
curl is being invoked without --cacert pointing at the workspace
ca.crt. The CA bundle is present in the auth workspace but curl
is not being told to trust it. Recent versions of the upload and download
Tasks wire this up automatically; older versions may need an explicit step.
Reference
- The
nexus-uploadandnexus-downloadTekton Tasks — Tasks that consume this RI. - Nexus ConnectorClass concept — the underlying ConnectorClass, including the forward-proxy URL derivation and the configurations exposed for other formats.