@gtrevorrow/oci-token-exchange 2.0.0-rc.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/README.md +252 -260
  2. package/dist/action/cli.d.ts +2 -0
  3. package/dist/action/index.d.ts +5 -0
  4. package/dist/action/index.js +41456 -0
  5. package/dist/action/index.js.map +1 -0
  6. package/dist/action/licenses.txt +714 -0
  7. package/dist/action/main.d.ts +6 -0
  8. package/dist/action/platforms/cli.d.ts +20 -0
  9. package/dist/action/platforms/github.d.ts +13 -0
  10. package/dist/action/platforms/types.d.ts +30 -0
  11. package/dist/action/sourcemap-register.js +1 -0
  12. package/dist/action/types.d.ts +134 -0
  13. package/dist/cli.d.ts +0 -1
  14. package/dist/index.js +27105 -22098
  15. package/dist/index.js.map +1 -1
  16. package/dist/licenses.txt +349 -46
  17. package/dist/main.d.ts +2 -2
  18. package/dist/platforms/cli.d.ts +6 -2
  19. package/dist/platforms/github.d.ts +5 -2
  20. package/dist/platforms/types.d.ts +7 -3
  21. package/dist/types.d.ts +29 -4
  22. package/package.json +30 -19
package/README.md CHANGED
@@ -5,19 +5,14 @@
5
5
  - [Installation](#installation)
6
6
  - [As GitHub Action](#as-github-action)
7
7
  - [As CLI Tool](#as-cli-tool)
8
- - [Usage](#usage)
9
- - [GitHub Actions](#github-actions)
10
- - [GitLab CI](#gitlab-ci)
11
- - [Option 1: Building from Source](#option-1-building-from-source)
12
- - [Option 2: Using npm Package](#option-2-using-npm-package)
13
- - [Bitbucket Pipelines](#bitbucket-pipelines)
14
- - [Option 1: Building from Source](#option-1-building-from-source-1)
15
- - [Option 2: Using npm Package](#option-2-using-npm-package-1)
16
- - [Standalone CLI Usage](#standalone-cli-usage)
17
- - [Debugging](#debugging)
18
- - [Environment Variables / Github Secrets](#environment-variables--github-secrets)
19
- - [Environment Variable Handling](#environment-variable-handling)
20
- - [How it Works](#how-it-works)
8
+ - [Usage](#usage)
9
+ - [Inputs And Outputs](#inputs-and-outputs)
10
+ - [GitHub Actions](#github-actions)
11
+ - [GitLab CI](#gitlab-ci)
12
+ - [Bitbucket Pipelines](#bitbucket-pipelines)
13
+ - [Standalone CLI Usage](#standalone-cli-usage)
14
+ - [Debugging](#debugging)
15
+ - [How it Works](#how-it-works)
21
16
  - [Semantic Versioning](#semantic-versioning)
22
17
  - [License](#license)
23
18
  - [Contributing](#contributing)
@@ -33,13 +28,19 @@ A tool to exchange OIDC tokens for [OCI session tokens](https://docs.oracle.com/
33
28
 
34
29
  ### As GitHub Action
35
30
 
36
- 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:
31
+ To use this tool as a step in your GitHub Actions workflow, reference it using a specific Git tag, commit SHA, or branch. The following options are available, managed automatically by the release workflow:
37
32
 
38
33
  * **`@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.
39
34
  * **`@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.
35
+ * **`@<full-commit-sha>` - Highest Integrity Pinning:** Pins to a single immutable commit. Use this for high-assurance production pipelines and strict supply-chain controls.
40
36
  * **`@latest` - Latest Release:** Points to the most recent release. This tag is automatically updated upon new releases by the release workflow.
41
37
  * **`@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.
42
38
 
39
+ Pinning guidance:
40
+ * Use `@<full-commit-sha>` for regulated or high-risk production environments where no automatic movement is acceptable.
41
+ * Use `@vX.Y.Z` when you want stable behavior with controlled, manual upgrades.
42
+ * Use `@vX` when you want automatic non-breaking updates within a major version.
43
+
43
44
  ```yaml
44
45
  # Recommended: Use the major version tag for automatic compatible updates
45
46
  - uses: gtrevorrow/oci-token-exchange-action@v1
@@ -47,6 +48,9 @@ To use this tool as a step in your GitHub Actions workflow, reference it using a
47
48
  # Alternative: Pin to a specific version (e.g., v1.1.0)
48
49
  # - uses: gtrevorrow/oci-token-exchange-action@v1.1.0
49
50
 
51
+ # Highest integrity: Pin to an exact commit SHA
52
+ # - uses: gtrevorrow/oci-token-exchange-action@<full-commit-sha>
53
+
50
54
  # Alternative: Use the latest release
51
55
  # - uses: gtrevorrow/oci-token-exchange-action@latest
52
56
  ```
@@ -55,225 +59,232 @@ To use this tool as a step in your GitHub Actions workflow, reference it using a
55
59
  ```bash
56
60
  npm install -g @gtrevorrow/oci-token-exchange
57
61
 
58
- # Install a specific version globally (e.g., 1.2.3)
59
- npm install -g @gtrevorrow/oci-token-exchange@1.2.3
60
-
61
- # Install a version with a specific tag (e.g., beta)
62
- npm install -g @gtrevorrow/oci-token-exchange@beta
63
- ```
64
-
65
- ## Usage
66
-
67
- ### GitHub Actions
68
- ```yaml
69
- - uses: gtrevorrow/oci-token-exchange-action@v1
62
+ # Install the published release tag you want to use.
63
+ # Replace <release-tag> with your chosen release tag or version.
64
+ npm install -g @gtrevorrow/oci-token-exchange@<release-tag>
65
+ ```
66
+
67
+ Stable releases are published with the `latest` npm dist-tag. Major-family
68
+ dist-tags such as `major-v1` are maintained manually after a release. For an
69
+ immutable installation, use an exact package version.
70
+
71
+ ## Usage
72
+
73
+ ### Inputs and Outputs
74
+
75
+ Use this section as the source of truth for:
76
+ - GitHub Action `with:` inputs
77
+ - Their mapped `INPUT_*` names and CLI environment variable names
78
+ - Platform-specific token variables for GitLab, Bitbucket, and local CLI usage
79
+ - Debug-related environment variables
80
+ - Action outputs
81
+
82
+ ### Inputs
83
+
84
+ | Action Input | CLI / Env Var | GitHub `INPUT_*` Var | Required | Default | Notes |
85
+ |-------------|---------------|----------------------|----------|---------|-------|
86
+ | `ci_platform` | `PLATFORM` | `INPUT_CI_PLATFORM` | No | `github` | Supported values: `github`, `gitlab`, `bitbucket`, `local`. For GitHub Actions, `ci_platform` is the canonical input. For non-GitHub usage, `PLATFORM` remains the backward-compatible alias. |
87
+ | `oidc_client_identifier` | `OIDC_CLIENT_IDENTIFIER` | `INPUT_OIDC_CLIENT_IDENTIFIER` | Yes | - | OCI IAM confidential client in `client_id:client_secret` form. |
88
+ | `domain_base_url` | `DOMAIN_BASE_URL` | `INPUT_DOMAIN_BASE_URL` | Yes | - | OCI Identity Domain base URL, for example `https://idcs-xxxxxxxxxxxx.identity.oraclecloud.com`. |
89
+ | `oci_tenancy` | `OCI_TENANCY` | `INPUT_OCI_TENANCY` | Yes | - | OCI tenancy OCID. |
90
+ | `oci_region` | `OCI_REGION` | `INPUT_OCI_REGION` | Yes | - | OCI region identifier, for example `us-ashburn-1`. |
91
+ | `oidc_audience` | `OIDC_AUDIENCE` | `INPUT_OIDC_AUDIENCE` | No | `https://cloud.oracle.com` | Audience requested when GitHub Actions mints the OIDC token. This is only used for the GitHub platform. |
92
+ | `oci_home` | `OCI_HOME` | `INPUT_OCI_HOME` | No | `OCI_HOME`, then `HOME`, then OS home directory | Base home folder under which the tool creates the `.oci` directory. Do not pass the `.oci` directory itself. |
93
+ | `oci_profile` | `OCI_PROFILE` | `INPUT_OCI_PROFILE` | No | `DEFAULT` | OCI CLI profile name to create or update. |
94
+ | `retry_count` | `RETRY_COUNT` | `INPUT_RETRY_COUNT` | No | `0` | Number of retry attempts for token exchange failures. |
95
+ | `res_type` | `RES_TYPE` | `INPUT_RES_TYPE` | No | - | Resource type for RPST token exchange, for example `ref_github`. If `res_type` is configured, the tool requests an RPST; otherwise it requests a UPST. |
96
+ | `rpst_exp` | `RPST_EXP` | `INPUT_RPST_EXP` | No | - | Optional RPST expiration in integer minutes. |
97
+
98
+ If `rpst_exp` is configured, `res_type` must also be configured. If `res_type` is not configured, UPST remains the default.
99
+
100
+ ### Platform Token Variables
101
+
102
+ | Platform | Variable | Required When | Notes |
103
+ |----------|----------|---------------|-------|
104
+ | GitHub Actions | GitHub runtime OIDC token | `ci_platform=github` | No manual token env var is required; the action requests the token from the GitHub runtime. |
105
+ | GitLab CI | `CI_JOB_JWT_V2` | `PLATFORM=gitlab` | In the examples below, map your `id_tokens` value into `CI_JOB_JWT_V2` before invoking the CLI. |
106
+ | Bitbucket Pipelines | `BITBUCKET_STEP_OIDC_TOKEN` | `PLATFORM=bitbucket` | Provided by Bitbucket when `oidc: true` is enabled for the step. |
107
+ | Local / standalone CLI | `LOCAL_OIDC_TOKEN` | `PLATFORM=local` | Provide your own OIDC token for local testing or custom runners. |
108
+
109
+ ### Outputs
110
+
111
+ | Output | Description |
112
+ |--------|-------------|
113
+ | `configured` | Set to `true` when configuration completes successfully. |
114
+ | `oci_config_path` | Absolute path to the generated OCI config file. |
115
+ | `oci_session_token_path` | Absolute path to the generated OCI session token file. |
116
+ | `oci_private_key_path` | Absolute path to the generated private key file. |
117
+
118
+ ### Debug Variables
119
+
120
+ | Context | Variable | Notes |
121
+ |---------|----------|-------|
122
+ | GitHub Actions | `ACTIONS_STEP_DEBUG` | Enables the built-in debug channel used by the action runtime. |
123
+ | GitHub Actions | `ACTIONS_RUNNER_DEBUG` | Optional runner-level tracing. |
124
+ | CLI / other runners | `DEBUG` | Set to `true` to enable verbose CLI logging. |
125
+
126
+ ### Variable Resolution
127
+
128
+ Variable resolution differs between GitHub Actions and CLI/non-GitHub usage:
129
+
130
+ 1. GitHub Actions path:
131
+ `GitHubPlatform` uses `@actions/core.getInput(...)`, which reads the GitHub Actions input values exposed through `INPUT_*`.
132
+ For example, `with: oci_region: ...` is read as `INPUT_OCI_REGION`.
133
+
134
+ 2. CLI / non-GitHub path:
135
+ `CLIPlatform` uses `resolveInput(...)`, which checks values in this order:
136
+ - plain environment variable such as `PLATFORM`, `OCI_HOME`, or `RETRY_COUNT`
137
+ - GitHub-style environment variable such as `INPUT_CI_PLATFORM`
138
+ - `OCI_*` prefixed environment variable
139
+ - `OIDC_*` prefixed environment variable
140
+
141
+ 3. Input-specific fallbacks:
142
+ Some values have additional runtime fallbacks after input resolution.
143
+ For example, `oci_home` falls back to `HOME` and then the OS home directory.
144
+
145
+ ### GitHub Actions
146
+
147
+ Use the example below together with the [Inputs and Outputs](#inputs-and-outputs) reference above.
148
+
149
+ ```yaml
150
+ - uses: gtrevorrow/oci-token-exchange-action@v1
70
151
  with:
71
152
  # ci_platform: 'github' # Optional: Defaults to 'github'. Other values: 'gitlab', 'bitbucket', 'local' (though 'github' is typical for Actions)
72
- oidc_client_identifier: ${{ secrets.OIDC_CLIENT_IDENTIFIER }}
73
- domain_base_url: ${{ vars.DOMAIN_BASE_URL }}
74
- oci_tenancy: ${{ secrets.OCI_TENANCY }}
75
- oci_region: ${{ secrets.OCI_REGION }}
76
- # Optional: Custom base folder for OCI config (.oci) directory
77
- # oci_home: ${{ secrets.OCI_HOME }}
153
+ oidc_client_identifier: ${{ secrets.OIDC_CLIENT_IDENTIFIER }}
154
+ domain_base_url: ${{ vars.DOMAIN_BASE_URL }}
155
+ oci_tenancy: ${{ secrets.OCI_TENANCY }}
156
+ oci_region: ${{ secrets.OCI_REGION }}
157
+ # Optional: Audience requested when GitHub mints the OIDC token
158
+ # oidc_audience: 'https://cloud.oracle.com'
159
+ # Optional: Custom base home folder under which the action creates .oci
160
+ # oci_home: ${{ secrets.OCI_HOME }}
78
161
  # Optional: Name of the OCI CLI profile to create. Defaults to 'DEFAULT'.
79
162
  # oci_profile: 'DEFAULT'
80
163
  # Optional: Number of retry attempts. Defaults to '0'.
81
- # retry_count: '0'
82
- ```
83
-
84
- ### GitLab CI
85
-
86
- #### Option 1: Building from Source
87
-
88
- This example clones the repository, builds the CLI, and then runs it.
89
-
90
- ```yaml
91
- # Use these YAML anchors to setup common tasks
92
- .oci_setup: &oci_setup |
93
- curl -LO https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh
94
- bash install.sh --accept-all-defaults
95
- source ~/.bashrc
96
-
97
- .clone_build_cli: &clone_build_cli |
98
- git clone https://github.com/gtrevorrow/oci-token-exchange-action.git
99
- cd oci-token-exchange-action
100
- npm ci
101
- npm run build:cli
102
-
103
- deploy:
104
- script:
105
- # Install OCI CLI
106
- - *oci_setup
107
-
108
- # Clone and build the token exchange CLI
109
- - *clone_build_cli
110
-
111
- # Export token from GitLab CI
112
- - export CI_JOB_JWT_V2="$(cat $CI_JOB_JWT_FILE)"
113
-
114
- # Run the built CLI
115
- - |
116
- cd dist &&
117
- PLATFORM=gitlab \
118
- OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
119
- DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \ # Changed from DOMAIN_URL
120
- OCI_TENANCY=${OCI_TENANCY} \
121
- OCI_REGION=${OCI_REGION} \
122
- RETRY_COUNT=3 \
123
- node cli.js
124
-
125
- # Verify OCI CLI configuration works
126
- - cd ../..
127
- - oci os ns get
128
-
129
- # Run only on main branch
130
- rules:
131
- - if: $CI_COMMIT_BRANCH == "main"
132
-
133
- # Configure OIDC token for GitLab
134
- id_tokens:
135
- ID_TOKEN:
136
- aud: https://cloud.oracle.com/gitlab
137
- ```
138
-
139
- #### Option 2: Using npm Package
140
-
141
- This example installs the CLI tool directly from npm.
142
-
143
- ```yaml
144
- # Use these YAML anchors to setup common tasks
145
- .oci_setup: &oci_setup |
146
- curl -LO https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh
147
- bash install.sh --accept-all-defaults
148
- source ~/.bashrc
149
-
150
- deploy_npm:
151
- script:
152
- # Install OCI CLI
153
- - *oci_setup
154
-
155
- # Install the token exchange CLI from npm
156
- - npm install -g @gtrevorrow/oci-token-exchange
157
-
158
- # Export token from GitLab CI
159
- - export CI_JOB_JWT_V2="$(cat $CI_JOB_JWT_FILE)"
160
-
161
- # Run the installed CLI
162
- - |
163
- PLATFORM=gitlab \
164
- OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
165
- DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \ # Changed from DOMAIN_URL
166
- OCI_TENANCY=${OCI_TENANCY} \
167
- OCI_REGION=${OCI_REGION} \
168
- RETRY_COUNT=3 \
169
- oci-token-exchange
170
-
171
- # Verify OCI CLI configuration works
172
- - oci os ns get
173
-
174
- # Run only on main branch
175
- rules:
176
- - if: $CI_COMMIT_BRANCH == "main"
177
-
178
- # Configure OIDC token for GitLab
179
- id_tokens:
180
- ID_TOKEN:
181
- aud: https://cloud.oracle.com/gitlab
182
- ```
183
-
184
- ### Bitbucket Pipelines
185
-
186
- #### Option 1: Building from Source
187
-
188
- This example clones the repository, builds the CLI, and then runs it.
189
-
190
- ```yaml
191
- image: node:20
192
-
193
- pipelines:
194
- default:
195
- - step:
196
- name: Setup OCI CLI with OIDC Token Exchange (Build from Source)
197
- oidc: true # Enable OIDC for Bitbucket
198
- script:
199
- # Setup OCI CLI
200
- - curl -LO https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh
201
- - bash install.sh --accept-all-defaults
202
- - export PATH=$PATH:/root/bin
203
-
204
- # Clone and build the token exchange CLI from GitHub
205
- - git clone https://github.com/gtrevorrow/oci-token-exchange-action.git
206
- - cd oci-token-exchange-action
207
- - npm ci
208
- - npm run build:cli
209
-
210
- # Run the built CLI for token exchange
211
- - >
212
- cd dist &&
213
- export PLATFORM=bitbucket &&
214
- export OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} &&
215
- export DOMAIN_BASE_URL=${DOMAIN_BASE_URL} && # Changed from DOMAIN_URL
216
- export OCI_TENANCY=${OCI_TENANCY} &&
217
- export OCI_REGION=${OCI_REGION} &&
218
- export RETRY_COUNT=3
219
- - node cli.js || exit 1
220
-
221
- # Verify OCI CLI works with generated token
222
- - cd ../..
223
- - oci os ns get
224
-
225
- # Preserve credentials for subsequent steps
226
- artifacts:
227
- - ".oci/**"
228
- - "private_key.pem"
229
- - "public_key.pem"
230
- - "session"
231
- ```
232
-
233
- #### Option 2: Using npm Package
234
-
235
- This example installs the CLI tool directly from npm.
236
-
237
- ```yaml
238
- image: node:20
239
-
164
+ # retry_count: '0'
165
+
166
+ ```
167
+
168
+ ### GitLab CI
169
+
170
+ This example follows the working setup in [.gitlab-ci.yml](.gitlab-ci.yml).
171
+ Replace `<release-tag>` with the published release tag or version you want to
172
+ use. The package is installed without modifying the consumer project's manifest,
173
+ the GitLab ID token is mapped to `CI_JOB_JWT_V2`, and the installed binary runs with `npx --no-install`.
174
+
175
+ ```yaml
176
+ image: node:24
177
+
178
+ variables:
179
+ HUSKY: "0"
180
+
181
+ .oci_setup: &oci_setup |
182
+ # Docker runners should only need Python 3 + venv support in the job image.
183
+ # Shell runners must provide python3 and python3 -m venv on the host.
184
+ python3 -m venv .oci-cli
185
+ . .oci-cli/bin/activate
186
+ python -m pip install --upgrade pip
187
+ pip install oci-cli
188
+
189
+ deploy:
190
+ script:
191
+ - *oci_setup
192
+
193
+ - npm install --no-save @gtrevorrow/oci-token-exchange@<release-tag>
194
+
195
+ - export CI_JOB_JWT_V2="$ID_TOKEN"
196
+
197
+ - |
198
+ PLATFORM=gitlab \
199
+ OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
200
+ DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \
201
+ OCI_TENANCY=${OCI_TENANCY} \
202
+ OCI_REGION=${OCI_REGION} \
203
+ OCI_HOME=${CI_PROJECT_DIR} \
204
+ OCI_PROFILE=${OCI_PROFILE} \
205
+ RETRY_COUNT=${RETRY_COUNT:-3} \
206
+ npx --no-install oci-token-exchange
207
+
208
+ - oci --auth security_token --config-file "$CI_PROJECT_DIR/.oci/config" --profile "${OCI_PROFILE:-DEFAULT}" os ns get
209
+
210
+ rules:
211
+ - if: $CI_COMMIT_BRANCH == "develop"
212
+
213
+ id_tokens:
214
+ ID_TOKEN:
215
+ aud: https://cloud.oracle.com/
216
+ ```
217
+
218
+ ### Bitbucket Pipelines
219
+
220
+ This example follows the working setup in [bitbucket-pipelines.yml](bitbucket-pipelines.yml).
221
+ Replace `<release-tag>` with the published release tag or version you want to
222
+ use. Both pipelines invoke the locally installed package with `npx --no-install`
223
+ and explicitly verify the generated OCI configuration.
224
+
225
+ ```yaml
226
+ image: node:24
227
+
240
228
  pipelines:
241
229
  default:
242
- - step:
243
- name: Setup OCI CLI with OIDC Token Exchange (npm Package)
244
- oidc: true # Enable OIDC for Bitbucket
245
- script:
246
- # Setup OCI CLI
247
- - curl -LO https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh
248
- - bash install.sh --accept-all-defaults
249
- - export PATH=$PATH:/root/bin
250
-
251
- # Install the token exchange CLI from npm
252
- - npm install -g @gtrevorrow/oci-token-exchange
253
-
254
- # Run the installed CLI for token exchange
255
- - >
256
- export PLATFORM=bitbucket &&
257
- export OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} &&
258
- export DOMAIN_BASE_URL=${DOMAIN_BASE_URL} && # Changed from DOMAIN_URL
259
- export OCI_TENANCY=${OCI_TENANCY} &&
260
- export OCI_REGION=${OCI_REGION} &&
261
- export RETRY_COUNT=3
262
- - oci-token-exchange || exit 1
263
-
264
- # Verify OCI CLI works with generated token
265
- - oci os ns get
266
-
267
- # Preserve credentials for subsequent steps
268
- artifacts:
269
- - ".oci/**"
270
- - "private_key.pem"
271
- - "public_key.pem"
272
- - "session"
273
- ```
274
-
275
- ### Standalone CLI Usage
276
- ```bash
230
+ - step:
231
+ name: Setup OCI CLI with OIDC Token Exchange
232
+ oidc: true
233
+ script:
234
+ - curl -LO https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh
235
+ - bash install.sh --accept-all-defaults
236
+ - export PATH=$PATH:/root/bin
237
+ - npm install --no-save @gtrevorrow/oci-token-exchange@<release-tag>
238
+ - |
239
+ PLATFORM=bitbucket \
240
+ OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
241
+ DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \
242
+ OCI_TENANCY=${OCI_TENANCY} \
243
+ OCI_REGION=${OCI_REGION} \
244
+ OCI_HOME=${BITBUCKET_CLONE_DIR} \
245
+ OCI_PROFILE=${OCI_PROFILE} \
246
+ RETRY_COUNT=${RETRY_COUNT:-3} \
247
+ npx --no-install oci-token-exchange
248
+ - oci --auth security_token --config-file "$BITBUCKET_CLONE_DIR/.oci/config" --profile "${OCI_PROFILE:-DEFAULT}" os ns get
249
+ artifacts:
250
+ - ".oci/**"
251
+ - "private_key.pem"
252
+ - "public_key.pem"
253
+ - "session"
254
+
255
+ branches:
256
+ main:
257
+ - step:
258
+ name: Setup OCI CLI with Published Package (Production)
259
+ oidc: true
260
+ script:
261
+ - curl -LO https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh
262
+ - bash install.sh --accept-all-defaults
263
+ - export PATH=$PATH:/root/bin
264
+ - npm install --no-save @gtrevorrow/oci-token-exchange@<release-tag>
265
+ - |
266
+ PLATFORM=bitbucket \
267
+ OIDC_CLIENT_IDENTIFIER=${OIDC_CLIENT_IDENTIFIER} \
268
+ DOMAIN_BASE_URL=${DOMAIN_BASE_URL} \
269
+ OCI_TENANCY=${OCI_TENANCY} \
270
+ OCI_REGION=${OCI_REGION} \
271
+ OCI_HOME=${BITBUCKET_CLONE_DIR} \
272
+ OCI_PROFILE=${OCI_PROFILE} \
273
+ RETRY_COUNT=${RETRY_COUNT:-3} \
274
+ npx --no-install oci-token-exchange
275
+ - oci --auth security_token --config-file "$BITBUCKET_CLONE_DIR/.oci/config" --profile "${OCI_PROFILE:-DEFAULT}" os ns get
276
+ artifacts:
277
+ - ".oci/**"
278
+ - "private_key.pem"
279
+ - "public_key.pem"
280
+ - "session"
281
+ ```
282
+
283
+ ### Standalone CLI Usage
284
+
285
+ See [Inputs and Outputs](#inputs-and-outputs) for the complete CLI environment variable reference.
286
+
287
+ ```bash
277
288
  # Install globally
278
289
  npm install -g @gtrevorrow/oci-token-exchange
279
290
 
@@ -281,9 +292,11 @@ npm install -g @gtrevorrow/oci-token-exchange
281
292
  export LOCAL_OIDC_TOKEN="your.jwt.token"
282
293
  # Optional: set custom OCI config home
283
294
  export OCI_HOME="/custom/home"
295
+ # Optional: set custom OCI CLI profile name (defaults to 'DEFAULT')
296
+ export OCI_PROFILE="myprofile"
284
297
  PLATFORM=local \
285
298
  OIDC_CLIENT_IDENTIFIER=your-client-identifier \
286
- DOMAIN_BASE_URL=https://your-domain.identity.oraclecloud.com \ # Changed from DOMAIN_URL
299
+ DOMAIN_BASE_URL=https://your-domain.identity.oraclecloud.com \
287
300
  OCI_TENANCY=your-tenancy-ocid \
288
301
  OCI_REGION=your-region \
289
302
  oci-token-exchange
@@ -294,47 +307,26 @@ oci os ns get
294
307
 
295
308
  ### Debugging
296
309
 
297
- To enable detailed logging, set the `DEBUG` environment variable to `true`:
298
-
299
- ```bash
300
- export DEBUG=true
301
- ```
302
-
303
- This will log additional information, such as token exchange requests and responses, to help with troubleshooting.
310
+ **GitHub Actions**
304
311
 
305
- ## Environment Variables / Github Secrets
312
+ - Add a repository or environment secret named `ACTIONS_STEP_DEBUG` with the value `true`, then reference it in the workflow (`env: ACTIONS_STEP_DEBUG: ${{ secrets.ACTIONS_STEP_DEBUG }}`). This enables the built-in debug channel that the action checks via `core.isDebug()`.
313
+ - Optional: set `ACTIONS_RUNNER_DEBUG` to `true` (also via secret) when you need runner-level tracing.
306
314
 
307
- The action supports flexible environment variable naming to make it easier to use across different platforms:
315
+ **CLI / other runners**
308
316
 
309
- | Variable | Alternate Names | Description | Required |
310
- |----------|----------------|-------------|----------|
311
- | `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 |
312
- | `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 |
313
- | `OCI_TENANCY` | `INPUT_OCI_TENANCY` | OCI tenancy OCID. GitHub Action input: `oci_tenancy`. CLI env var: `OCI_TENANCY`. | Yes |
314
- | `OCI_REGION` | `INPUT_OCI_REGION` | OCI region identifier. GitHub Action input: `oci_region`. CLI env var: `OCI_REGION`. | Yes |
315
- | `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`) |
316
- | `RETRY_COUNT` | `INPUT_RETRY_COUNT` | Number of retry attempts. GitHub Action input: `retry_count`. CLI env var: `RETRY_COUNT`. | No (default: `0`) |
317
- | `LOCAL_OIDC_TOKEN` | - | OIDC token when using `PLATFORM=local` (CLI only). | Yes, when platform=local |
318
- | `CI_JOB_JWT_V2` | - | GitLab CI JWT token (used when `PLATFORM=gitlab` for CLI). | Yes, when platform=gitlab |
319
- | `BITBUCKET_STEP_OIDC_TOKEN` | - | Bitbucket OIDC token (used when `PLATFORM=bitbucket` for CLI). | Yes, when platform=bitbucket |
320
- | `DEBUG` | - | Enable debug output (CLI env var). | No (default: `false`) |
321
- | `OCI_HOME` | `INPUT_OCI_HOME` | Base folder for OCI config (.oci) directory. GitHub Action input: `oci_home`. CLI env var: `OCI_HOME`. | No |
322
- | `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 |
317
+ Set the `DEBUG` environment variable to `true` before invoking the tool:
323
318
 
324
- ### Environment Variable Handling
325
-
326
- Variables can be provided in two ways:
327
-
328
- 1. **GitHub Actions Format**: Variables in the format `INPUT_VARIABLE_NAME` (used by GitHub Actions)
329
- 2. **Standard Format**: Plain environment variables matching the exact names listed above
330
-
331
- The GitHub Action automatically maps variables from GitHub's format to the standard format, but if you're using the CLI directly, use the variable names exactly as shown above.
319
+ ```bash
320
+ export DEBUG=true
321
+ ```
332
322
 
333
- ## How it Works
323
+ This produces verbose logs (requests/responses, file paths, etc.) to simplify troubleshooting.
324
+
325
+ ## How it Works
334
326
 
335
327
  1. Generates an RSA key pair
336
328
  2. Requests a GitHub OIDC JWT token
337
- 3. Exchanges the JWT for an OCI UPST token
329
+ 3. Exchanges the JWT for an OCI UPST token, or an RPST token when `res_type` is configured
338
330
  4. Configures the OCI CLI with the obtained credentials
339
331
 
340
332
  ## Semantic Versioning
package/dist/action/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/action/index.d.ts ADDED
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Copyright (c) 2021, 2025 Oracle and/or its affiliates.
3
+ * Licensed under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl.
4
+ */
5
+ export * from "./main";