#2503 push SNAPSHOT Maven artifacts to github Packages

.github/workflows/build.yml

@@ -49,6 +49,7 @@ jobs:
     permissions:
       actions: read
       contents: read
+      packages: write
 
     strategy:
       fail-fast: false
@@ -75,9 +76,21 @@ jobs:
       - name: Check with Gradle
         run: ./gradlew check --scan --full-stacktrace
 
+      - name: Publish Maven packages to GitHub Packages
+        if: ${{ github.event_name == 'push' }}
+        run: ./gradlew publish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPOSITORY_URL: 'https://maven.pkg.github.com/google/android-fhir'
+          # Use SNAPSHOT Prefix to follow Maven convention
+          ARTIFACT_VERSION_SUFFIX: SNAPSHOT
+
       - name: Release artifacts to local repo
         run: ./gradlew publishReleasePublicationToCIRepository --scan
-      - name: Upload maven repo
+        env:
+          ARTIFACT_VERSION_SUFFIX: build_${{ github.run_id }}
+
+      - name: Upload artifact maven-repository.zip
         uses: actions/upload-artifact@v4
         with:
           name: maven-repository

buildSrc/src/main/kotlin/Releases.kt

@@ -119,20 +119,33 @@ fun Project.publishArtifact(artifact: LibraryArtifact) {
             licenses {
               license {
                 name.set("The Apache License, Version 2.0")
-                url.set("http://www.apache.org/licenses/LICENSE-2.0.txt")
+                url.set("https://www.apache.org/licenses/LICENSE-2.0.txt")
               }
             }
           }
           repositories {
             maven {
               name = "CI"
-              url = uri("file://${rootProject.buildDir}/ci-repo")
+              url =
+                if (System.getenv("REPOSITORY_URL") != null) {
+                  // REPOSITORY_URL is defined in .github/workflows/build.yml
+                  uri(System.getenv("REPOSITORY_URL"))
+                } else {
+                  uri("file://${rootProject.buildDir}/ci-repo")
+                }
               version =
                 if (project.providers.environmentVariable("GITHUB_ACTIONS").isPresent) {
-                  "${artifact.version}-build_${System.getenv("GITHUB_RUN_ID")}"
+                  // ARTIFACT_VERSION_SUFFIX is defined in .github/workflows/build.yml
+                  "${artifact.version}-${System.getenv("ARTIFACT_VERSION_SUFFIX")}"
                 } else {
                   artifact.version
                 }
+              if (System.getenv("GITHUB_TOKEN") != null) {
+                credentials {
+                  username = System.getenv("GITHUB_ACTOR")
+                  password = System.getenv("GITHUB_TOKEN")
+                }
+              }
             }
           }
         }

docs/use/Snapshots.md

@@ -0,0 +1,76 @@
+# Snapshots
+
+You can test the latest Android FHIR SDK libraries using the snapshot versions published on GitHub Packages. 
+
+They are unreleased versions of the library built from the `HEAD` of the main branch and have the `-SNAPSHOT` suffix in their version numbers.
+
+They can be found here: https://github.com/google?tab=packages&repo_name=android-fhir
+
+> :warning: The snapshots are for testing and development purposes only. They are not QA tested and not production ready. Do **NOT** use them in production.
+
+# How to use SNAPSHOT artifacts
+
+## Configure GitHub maven repositories in `build.gradle.kts`
+
+Since these artifacts are deployed on GitHub Packages, a `username`/`GitHub token` pair is required as explained in [Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages). The token needs at least the `read:packages` scope.
+
+This can be securely managed by placing the credentials in the `local.properties` file and loading them with `gradleLocalProperties`. With this approach, the file `build.gradle.kts` will look like:
+
+```kotlin
+import com.android.build.gradle.internal.cxx.configure.gradleLocalProperties
+
+plugins {
+  ...
+}
+
+android {
+  ...
+  repositories{
+    maven {
+      url = uri("https://maven.pkg.github.com/google/android-fhir")
+      credentials {
+        username = gradleLocalProperties(rootDir).getProperty("gpr.user") ?: System.getenv("GPR_USER")
+        password = gradleLocalProperties(rootDir).getProperty("gpr.key") ?: System.getenv("GPR_KEY")
+      }
+    }
+  }
+}
+
+dependencies {
+}
+```
+
+Notice the environment variables `GPR_USER`/`GPR_KEY` used in this file.
+
+Then, the file `local.properties` will need to be created in the project root folder:
+
+```dotenv
+sdk.dir=<path to Android SDK>
+gpr.user=<Your GitHub Account>
+gpr.key=<A GitHub token>
+```
+
+## Declare dependencies
+
+To include the snapshots in the dependencies of your app, modify `build.gradle.kts` in your app:
+
+```kotlin
+dependencies {
+  ...
+  implementation("com.google.android.fhir:engine:<engine-version>-SNAPSHOT")
+  implementation("com.google.android.fhir:data-capture:<dc-version>-SNAPSHOT")
+}
+```
+
+The versions `<...-version>` can be found in https://github.com/google?tab=packages&repo_name=android-fhir
+
+## How SNAPSHOT versions are managed by Gradle
+
+The complete documentation can be found in the section [Declaring a changing version](https://docs.gradle.org/current/userguide/dynamic_versions.html#sub:declaring_dependency_with_changing_version).
+
+To summarize:
+- By default, Gradle caches changing versions of dependencies for **24 hours**
+- Dependency caching can be [controlled programmatically](https://docs.gradle.org/current/userguide/dynamic_versions.html#sec:controlling_dependency_caching_programmatically)
+- The `--refresh-dependencies` option in command line tells Gradle to ignore all cached versions
+
+

mkdocs.yaml

@@ -42,6 +42,7 @@ nav:
               - use/WFL/Compile-and-Execute-CQL.md
       - use/Extensions.md
       - API Doc: use/api.md
+      - Use Snapshots: use/Snapshots.md
   - Contributors:
       - Contributing: contrib/index.md
       - Codespaces: contrib/codespaces.md