@gtrevorrow/oci-token-exchange 1.0.0 → 1.1.0

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Oracle and/or its affiliates.
+Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 
 The Universal Permissive License (UPL), Version 1.0
 

package/README.md

@@ -24,7 +24,7 @@
 
 # OCI Token Exchange
 
-A tool to exchange OIDC tokens for [OCI session tokens](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm), supporting multiple CI platforms:
+A tool to exchange OIDC tokens for [OCI session tokens](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm), supporting multiple CI/CD platforms:
 - GitHub Actions
 - GitLab CI
 - Bitbucket Pipelines
@@ -32,17 +32,29 @@ A tool to exchange OIDC tokens for [OCI session tokens](https://docs.oracle.com/
 ## Installation
 
 ### As GitHub Action
+
+To use this tool as a step in your GitHub Actions workflow, reference it using a specific Git tag or branch. The following options are available, managed automatically by the release workflow:
+
+*   **`@vX` (e.g., `@v1`) - Recommended:** Points to the latest stable release within a specific major version (e.g., the latest `v1.x.y`). This tag is automatically updated upon new releases, allowing you to receive compatible updates and bug fixes without breaking changes.
+*   **`@vX.Y.Z` (e.g., `@v1.1.0`) - Specific Version:** Pins the action to an exact release version created by semantic-release. Use this if you need absolute stability and want to control updates manually.
+*   **`@latest` - Latest Release:** Points to the most recent release. This tag is automatically updated upon new releases by the release workflow.
+*   **`@main` - Bleeding Edge (Not Recommended):** Runs the action directly from the latest commit on the `main` branch. This is unstable and should generally be avoided in production workflows.
+
 ```yaml
+# Recommended: Use the major version tag for automatic compatible updates
 - uses: gtrevorrow/oci-token-exchange-action@v1
+
+# Alternative: Pin to a specific version (e.g., v1.1.0)
+# - uses: gtrevorrow/oci-token-exchange-action@v1.1.0 
+
+# Alternative: Use the latest release
+# - uses: gtrevorrow/oci-token-exchange-action@latest
 ```
 
 ### As CLI Tool
 ```bash
 npm install -g @gtrevorrow/oci-token-exchange
 
-# Install the latest version globally
-npm install -g @gtrevorrow/oci-token-exchange
-
 # Install a specific version globally (e.g., 1.2.3)
 npm install -g @gtrevorrow/oci-token-exchange@1.2.3
 
@@ -56,10 +68,17 @@ npm install -g @gtrevorrow/oci-token-exchange@beta
 ```yaml
 - uses: gtrevorrow/oci-token-exchange-action@v1
   with:
-    oidc_client_identifier: ${{ secrets.OIDC_CLIENT_ID }}
-    domain_base_url: ${{ secrets.DOMAIN_URL }}
+    # ci_platform: 'github' # Optional: Defaults to 'github'. Other values: 'gitlab', 'bitbucket', 'local' (though 'github' is typical for Actions)
+    oidc_client_identifier: ${{ secrets.OIDC_CLIENT_IDENTIFIER }} 
+    domain_base_url: ${{ vars.DOMAIN_BASE_URL }} 
     oci_tenancy: ${{ secrets.OCI_TENANCY }}
     oci_region: ${{ secrets.OCI_REGION }}
+    # Optional: Custom base folder for OCI config (.oci) directory
+    # oci_home: ${{ secrets.OCI_HOME }}
+    # Optional: Name of the OCI CLI profile to create. Defaults to 'DEFAULT'.
+    # oci_profile: 'DEFAULT' 
+    # Optional: Number of retry attempts. Defaults to '0'.
+    # retry_count: '0'
 ```
 
 ### GitLab CI
@@ -96,8 +115,8 @@ deploy:
     - |
       cd dist &&
       PLATFORM=gitlab \
-      OIDC_CLIENT_ID=${OIDC_CLIENT_ID} \
-      DOMAIN_URL=${DOMAIN_URL} \
+      OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
+      DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \ # Changed from DOMAIN_URL
       OCI_TENANCY=${OCI_TENANCY} \
       OCI_REGION=${OCI_REGION} \
       RETRY_COUNT=3 \
@@ -142,8 +161,8 @@ deploy_npm:
     # Run the installed CLI
     - |
       PLATFORM=gitlab \
-      OIDC_CLIENT_ID=${OIDC_CLIENT_ID} \
-      DOMAIN_URL=${DOMAIN_URL} \
+      OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
+      DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \ # Changed from DOMAIN_URL
       OCI_TENANCY=${OCI_TENANCY} \
       OCI_REGION=${OCI_REGION} \
       RETRY_COUNT=3 \
@@ -192,8 +211,8 @@ pipelines:
           - >
             cd dist &&
             export PLATFORM=bitbucket &&
-            export OIDC_CLIENT_ID=${OIDC_CLIENT_ID} &&
-            export DOMAIN_URL=${DOMAIN_URL} &&
+            export OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} &&
+            export DOMAIN_BASE_URL=${DOMAIN_BASE_URL} && # Changed from DOMAIN_URL
             export OCI_TENANCY=${OCI_TENANCY} &&
             export OCI_REGION=${OCI_REGION} &&
             export RETRY_COUNT=3
@@ -235,8 +254,8 @@ pipelines:
           # Run the installed CLI for token exchange
           - >
             export PLATFORM=bitbucket &&
-            export OIDC_CLIENT_ID=${OIDC_CLIENT_ID} &&
-            export DOMAIN_URL=${DOMAIN_URL} &&
+            export OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} &&
+            export DOMAIN_BASE_URL=${DOMAIN_BASE_URL} && # Changed from DOMAIN_URL
             export OCI_TENANCY=${OCI_TENANCY} &&
             export OCI_REGION=${OCI_REGION} &&
             export RETRY_COUNT=3
@@ -260,9 +279,11 @@ npm install -g @gtrevorrow/oci-token-exchange
 
 # Run with required environment variables
 export LOCAL_OIDC_TOKEN="your.jwt.token"
+# Optional: set custom OCI config home
+export OCI_HOME="/custom/home"
 PLATFORM=local \
-OIDC_CLIENT_ID=your-client-id \
-DOMAIN_URL=https://your-domain.identity.oraclecloud.com \
+OIDC_CLIENT_IDENTIFIER=your-client-identifier \
+DOMAIN_BASE_URL=https://your-domain.identity.oraclecloud.com \ # Changed from DOMAIN_URL
 OCI_TENANCY=your-tenancy-ocid \
 OCI_REGION=your-region \
 oci-token-exchange
@@ -287,16 +308,18 @@ The action supports flexible environment variable naming to make it easier to us
 
 | Variable | Alternate Names | Description | Required |
 |----------|----------------|-------------|----------|
-| `OIDC_CLIENT_IDENTIFIER` | `INPUT_OIDC_CLIENT_IDENTIFIER` | OIDC client identifier | Yes |
-| `DOMAIN_BASE_URL` | `INPUT_DOMAIN_BASE_URL` | Base URL of OCI Identity Domain | Yes |
-| `OCI_TENANCY` | `INPUT_OCI_TENANCY` | OCI tenancy OCID | Yes |
-| `OCI_REGION` | `INPUT_OCI_REGION` | OCI region identifier | Yes |
-| `PLATFORM` | `INPUT_PLATFORM` | CI platform (`github`, `gitlab`, `bitbucket`, or `local`) | No (default: `github`) |
-| `RETRY_COUNT` | `INPUT_RETRY_COUNT` | Number of retry attempts | No (default: `0`) |
-| `LOCAL_OIDC_TOKEN` | - | OIDC token when using PLATFORM=local | Yes, when platform=local |
-| `CI_JOB_JWT_V2` | - | GitLab CI JWT token | Yes, when platform=gitlab |
-| `BITBUCKET_STEP_OIDC_TOKEN` | - | Bitbucket OIDC token | Yes, when platform=bitbucket |
-| `DEBUG` | - | Enable debug output | No (default: `false`) |
+| `OIDC_CLIENT_IDENTIFIER` | `INPUT_OIDC_CLIENT_IDENTIFIER` | The `client_id:client_secret` string for your confidential OAuth client application. This string is the content used for HTTP Basic Authentication (prior to Base64 encoding), as typically used with the OAuth 2.0 client credentials grant type. The action/tool handles the Base64 encoding. This client application must be registered in the OCI IAM domain and listed in the `oauthClients` attribute of your Identity Propagation Trust policy. This identifies the application making the token exchange request. The client credential derived from this identifier is used to validate the client performing the token exchange. It's important to understand that this is not analogous to a static, long-lived API key; you cannot authenticate and authorize calls to OCI APIs using these client credentials directly. Instead, it serves as an additional layer of protection (in addition to the impersonation rules defined in the trust policy) to ensure that only authorized clients can perform a token exchange. This is especially relevant in contexts like GitHub Actions, where all repositories share a single OCI OIDC provider that signs the tokens it issues with the same private key (i.e., the signing key is not unique per repository or workflow). GitHub Action input: `oidc_client_identifier`. CLI env var: `OIDC_CLIENT_IDENTIFIER`. | Yes |
+| `DOMAIN_BASE_URL` | `INPUT_DOMAIN_BASE_URL` | Base URL of OCI Identity Domain. GitHub Action input: `domain_base_url`. CLI env var: `DOMAIN_BASE_URL`. | Yes |
+| `OCI_TENANCY` | `INPUT_OCI_TENANCY` | OCI tenancy OCID. GitHub Action input: `oci_tenancy`. CLI env var: `OCI_TENANCY`. | Yes |
+| `OCI_REGION` | `INPUT_OCI_REGION` | OCI region identifier. GitHub Action input: `oci_region`. CLI env var: `OCI_REGION`. | Yes |
+| `PLATFORM` | `INPUT_CI_PLATFORM` | CI platform. GitHub Action input: `ci_platform` (default: `github`). CLI env var: `PLATFORM` (`github`, `gitlab`, `bitbucket`, or `local`). | No (default: `github`) |
+| `RETRY_COUNT` | `INPUT_RETRY_COUNT` | Number of retry attempts. GitHub Action input: `retry_count`. CLI env var: `RETRY_COUNT`. | No (default: `0`) |
+| `LOCAL_OIDC_TOKEN` | - | OIDC token when using `PLATFORM=local` (CLI only). | Yes, when platform=local |
+| `CI_JOB_JWT_V2` | - | GitLab CI JWT token (used when `PLATFORM=gitlab` for CLI). | Yes, when platform=gitlab |
+| `BITBUCKET_STEP_OIDC_TOKEN` | - | Bitbucket OIDC token (used when `PLATFORM=bitbucket` for CLI). | Yes, when platform=bitbucket |
+| `DEBUG` | - | Enable debug output (CLI env var). | No (default: `false`) |
+| `OCI_HOME` | `INPUT_OCI_HOME` | Base folder for OCI config (.oci) directory. GitHub Action input: `oci_home`. CLI env var: `OCI_HOME`. | No |
+| `OCI_PROFILE` | `INPUT_OCI_PROFILE` | Name of the OCI CLI profile to create. GitHub Action input: `oci_profile`. CLI env var: `OCI_PROFILE`. Defaults to `DEFAULT`. | No |
 
 ### Environment Variable Handling
 
@@ -326,4 +349,3 @@ This action is licensed under the [Universal Permissive License v1.0 (UPL-1.0)](
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
-````

package/dist/index.d.ts

@@ -2,4 +2,4 @@
  * Copyright (c) 2021, 2025 Oracle and/or its affiliates.
  * Licensed under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl.
  */
-export * from './main';
+export * from "./main";