https://github.com/veupathdb/maven-packages
Maven artifact repository.
https://github.com/veupathdb/maven-packages
Last synced: 4 months ago
JSON representation
Maven artifact repository.
- Host: GitHub
- URL: https://github.com/veupathdb/maven-packages
- Owner: VEuPathDB
- Created: 2021-03-16T16:39:08.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-31T15:47:23.000Z (about 1 year ago)
- Last Synced: 2025-09-04T05:28:42.725Z (10 months ago)
- Homepage:
- Size: 83.4 MB
- Stars: 0
- Watchers: 23
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.adoc
Awesome Lists containing this project
README
= Maven Package Repo
:toc:
:toclevels: 3
== Setup
To pull or push artifacts from/to this repository, the `~/.gradle/gradle.properties` file must be created or edited with the following variables.
.`gradle.properties`
[source, properties]
----
gpr.user= <1>
gpr.key= <2>
----
<1> Your GitHub username
<2> A GitHub personal access token (see: https://docs.github.com/en/packages/learn-github-packages/about-github-packages#authenticating-to-github-packages[the GitHub documentation]) for an overview, or https://github.com/settings/tokens[click here] to generate a new personal token. You must pick at least the "read:packages" scope to download artifacts, and "write:packages" to upload.
== Pulling Packages
=== Gradle
To consume libraries hosted in this repo, the following must be added to your `build.gradle.kts` file's repositories block.
.`build.gradle.kts`
[source, kotlin]
----
// root repositories definition
repositories {
// other repo defs such as mavenCentral()
maven {
name = "GitHubPackages"
url = uri("https://maven.pkg.github.com/veupathdb/maven-packages")
credentials {
username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_USERNAME")
password = project.findProperty("gpr.key") as String? ?: System.getenv("GITHUB_TOKEN")
}
}
}
----
The fallback values `GITHUB_USERNAME` and `GITHUB_TOKEN` will be used when building the project in Jenkins.
=== Docker/Docker Compose
Building Docker images that depend on packages in this repo requires passing the GitHub access token to the image build.
This can be done through Docker's https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg[--build-arg] argument.
==== Configuring Docker
To enable passing the build-time credentials to Docker, the following https://docs.docker.com/engine/reference/builder/#arg[build args]
must be added to your project's `Dockerfile`.
These build args will become environment variables at build time, but will not appear in the built image.
.Dockerfile
[source, dockerfile]
----
FROM ...
ARG GITHUB_USERNAME
ARG GITHUB_TOKEN
...
----
==== Building with Docker
[source, shell-session]
----
$ docker build -t 'my-image' --build-arg=GITHUB_USERNAME=my-github-username --build-arg=GITHUB_TOKEN=my-access-token .
----
==== Building with Docker Compose
[source, shell-session]
----
$ docker-compose build --build-arg GITHUB_USERNAME=my-github-username --build-arg GITHUB_TOKEN=my-access-token
----
== Publishing Packages
=== Gradle
==== Configuration
Apply the following changes to your `build.gradle.kts` file.
. Add the `maven-publish` plugin to the plugins block.
+
[source, kotlin]
----
// root plugins closure
plugins {
// other plugins
`maven-publish`
}
----
. Configure gradle to produce a sources jar and a javadoc jar.
+
[source, kotlin]
----
java {
withSourcesJar()
withJavadocJar()
}
----
. Add a `publishing` block.
+
[source, kotlin]
----
publishing {
}
----
. Add the publish target repository
+
[source, kotlin]
----
publishing {
repositories {
maven {
name = "GitHub"
url = uri("https://maven.pkg.github.com/veupathdb/maven-packages")
credentials {
username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
}
}
}
}
----
. Add a publication for your project.
+
[source, kotlin]
----
publishing {
repositories {
...
}
publications {
create("gpr") {
from(components["java"])
}
}
}
----
. Optionally configure the generated pom following the instructions https://docs.gradle.org/current/userguide/publishing_maven.html[in the Gradle docs]. An example of a customized pom can be found in https://github.com/VEuPathDB/lib-jaxrs-container-core/blob/master/build.gradle.kts#L67[the container core lib's build file]
==== Publishing
Once your `build.gradle.kts` file has been updated with the publishing configuration, publishing artifacts can be done with the following command:
[source, shell]
----
./gradlew publish
----
== Automated Releases
=== Gradle
Using GitHub's workflows, the process of publishing an artifact can be handled automatically on tagging a git repo.
To set this up:
. Add your username and publishing token to the repository's secrets (in the repo's settings). The username should be under the key `USERNAME` and the your GitHub personal access token under the key `TOKEN`
. Create a new file in your repo's root directory at the path `.github/workflows/release.yml`
+
The contents of the `release.yml` file should be as follows:
+
.`release.yml`
[source, yaml]
----
name: Artifact Publish
on:
push:
tags:
- '*'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup
uses: actions/setup-java@v1
with:
java-version: 15
- name: Publish Package
run: gradle publish
env:
USERNAME: ${{ secrets.USERNAME }}
TOKEN: ${{ secrets.TOKEN }}
----
After pushing up the new file, any tagged commit to the repository will be automatically built and deployed to GitHub Packages.
== Appendix: Authentication Use Cases
How are a username/token combination transferred to Github during the following interations?
. Manually deploy new artifacts: uses gradle.properties (or USERNAME/TOKEN env vars as backup)
. Automatically deploy new artifacts: uses creds stored in the github repo
. Local build into jars: uses gradle.properties (or GITHUB_* env vars as backup) with make jar
. Local build into docker images: uses GITHUB_* env vars with make docker or extended docker build line
. Local build with docker-compose: uses user-specified env vars with extended docker-compose build line
. Jenkins build into docker images: use either env vars with extended docker-compose build line