Skip to content

Commit

Permalink
Improve readme (jfrog#181)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sverdlov93
sverdlov93 authored Aug 12, 2024
1 parent ea984f0 commit c0bbcc1
Showing 1 changed file with 80 additions and 88 deletions.
168 changes: 80 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

- [Overview](#overview)
- [Usage](#usage)
- [Authorization](#authorization)
- [Authentication Methods](#Authentication-Methods)
- [Setting the build name and build number when publishing build-info to Artifactory](#setting-the-build-name-and-build-number-when-publishing-build-info-to-artifactory)
- [Setting JFrog CLI version](#setting-jfrog-cli-version)
- [Setting the JFrog project key](#setting-the-jfrog-project-key)
Expand All @@ -29,7 +29,7 @@ This GitHub Action downloads, installs and configures [JFrog CLI](https://docs.j

Additionally, the Action incorporates the following features when utilizing JFrog CLI to interact with the JFrog Platform:

- Two distinct methods are available for authenticating with the JFrog Platform. Explore more details [here](#authorization)
- Three distinct methods are available for authenticating with the JFrog Platform. Explore more details [here](#Authentication-Methods)
- There's no need to add the _build name_ and _build number_ options and arguments to commands which accept them.
All build related operations will be automatically recorded with the _Workflow Name_ as build name and _Run Number_ as build number.

Expand All @@ -38,28 +38,21 @@ Additionally, the Action incorporates the following features when utilizing JFro
```yml
- uses: jfrog/setup-jfrog-cli@v4
- run: jf --version
# + Authentication method
```

## Authorization
## Authentication Methods

JFrog CLI operates in conjunction with the JFrog Platform. In order to facilitate this connection, certain connection details of the JFrog Platform must be provided.
There exist two methods to provide these details, and you only need to choose **one** method:
JFrog CLI integrates with the JFrog Platform. In order to facilitate this connection, certain connection details of the JFrog Platform must be provided.
There exist three methods to provide these details, and you only need to choose **one** method:

<details>
<summary>Connecting to JFrog using secrets</summary>
### General
You can choose one of the following two methods to set the connection details to the JFrog Platform as secrets:
- [Storing the connection details using separate environment variables](#storing-the-connection-details-using-separate-environment-variables)
- [Storing the connection details using single Config Token](#storing-the-connection-details-using-single-config-token)
<summary>🔐 Storing the connection details using environment variables</summary>

### Storing the connection details using separate environment variables
###
The connection details of the JFrog platform used by this action can be stored as [GitHub secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) (or [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/variables) for non-secret values)

The connection details of the JFrog platform used by JFrog CLI can be stored as secrets.
You can use one of the following two methods to define and store the JFrog Platform connection details as secrets.
You can set the connection details to your JFrog Platform by using one of the following environment variables combinations:
You can set the connection details to your JFrog Platform by using one of the following combinations:

1. JF_URL (no authentication)
2. JF_URL + JF_USER + JF_PASSWORD (basic authentication)
Expand All @@ -70,75 +63,30 @@ You can use these environment variables in your workflow as follows:
```yml
- uses: jfrog/setup-jfrog-cli@v4
env:
# JFrog platform url (for example: https://acme.jfrog.io)
JF_URL: ${{ vars.JF_URL }}
# JFrog Platform url
JF_URL: ${{ vars.JF_URL }} # or 'https://acme.jfrog.io'

# Basic authentication credentials
JF_USER: ${{ secrets.JF_USER }}
JF_PASSWORD: ${{ secrets.JF_PASSWORD }}
or
# or
# JFrog Platform access token
JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
- run: |
jf rt ping
```
| Important: If both Config Token(`JF_ENV_*`) and separate environment variables(`JF_URL`, ...) are provided, the default config will be the Config Token. To make the above separate environment variables as the default config use `jf c use setup-jfrog-cli-server` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### Storing the connection details using single Config Token

1. Make sure JFrog CLI is installed on your local machine by running `jf -v`.
2. Configure the details of the JFrog platform by running `jf c add`.
3. Export the details of the JFrog platform you configured, using the server ID you chose. Do this by running `jf c export <SERVER ID>`.
4. Copy the generated Config Token to the clipboard and save it as a secret on GitHub.

To use the saved JFrog platform configuration in the workflow, all you need to do it to expose the secret to the workflow.
The secret should be exposed as an environment variable with the _JF*ENV*_ prefix.
Here's how you do this:

```yml
- uses: jfrog/setup-jfrog-cli@v4
env:
JF_ENV_1: ${{ secrets.JF_SECRET_ENV_1 }}
- run: |
# Ping the server
jf rt ping
```

As you can see in the example above, we created a secret named _JF_SECRET_ENV_1_ and exposed it to the workflow
as the _JF_ENV_1_ environment variable. That's it - the ping command will now ping the configured Artifactory server.

If you have multiple Config Tokens as secrets, you can use all of them in the workflow as follows:

```yml
- uses: jfrog/setup-jfrog-cli@v4
env:
JF_ENV_1: ${{ secrets.JF_SECRET_ENV_1 }}
JF_ENV_2: ${{ secrets.JF_SECRET_ENV_2 }}
- run: |
# Set the utilized JFrog configuration by providing the server ID (configured by the 'jf c add' command).
jf c use local-1
# Ping local-1 Artifactory server
jf rt ping
# Now use the second sever configuration exposed to the Action.
jf c use local-2
# Ping local-2 Artifactory server
jf rt ping
```

| Important: When exposing more than one JFrog configuration to the Action, you should always add the `jf c use` command to specify the server to use. |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |

</details>
<details>
<summary>Connecting to JFrog using OIDC (OpenID Connect)</summary>
<summary>👤 Connecting to JFrog using OIDC (OpenID Connect)</summary>
### General
The sensitive connection details, such as the access token used by JFrog CLI on the JFrog platform, can be automatically generated by the action instead of storing it as a secret in GitHub.
This is made possible by leveraging the OpenID-Connect (OIDC) protocol. This protocol can authenticate the workflow issuer and supply a valid access token, requiring only the JF_URL environment variable. Learn more about this integration in [this](https://jfrog.com/blog/secure-access-development-jfrog-github-oidc) blog post.
This is made possible by leveraging the OpenID-Connect (OIDC) protocol.
This protocol can authenticate the workflow issuer and supply a valid access token, requiring only the JF_URL environment variable.
Learn more about this integration in [this](https://jfrog.com/blog/secure-access-development-jfrog-github-oidc) blog post.
To utilize the OIDC protocol, follow these steps:
### JFrog Platform configuration
Expand All @@ -152,11 +100,11 @@ To utilize the OIDC protocol, follow these steps:
![Configure OIDC integration](images/configure_oidc_integration.png)

| NOTE: |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| The value specified as the 'Provider Name' should be used as the oidc-provider-name input in [Workflow configuration step 2](#workflowstep2) below. |
| The 'Audience' field does not represent the 'aud' claim for insertion into the identity-mapping in [Platform configuration step 2](#platformstep2) below. Only the claims included in the Claims Json created during step 2 will be validated. |

<div id="platformstep2"/>
<div id="platformstep2"></div>

2. **Configure an identity mapping**: This phase sets an integration between a particular GitHub repository to the JFrog platform.

Expand All @@ -173,6 +121,8 @@ To utilize the OIDC protocol, follow these steps:
}
```



### Workflow configuration

1. **Set required permissions**: In the course of the protocol's execution, it's imperative to acquire a JSON Web Token (JWT) from GitHub's OIDC provider. To request this token, it's essential to configure the specified permission in the workflow file:
Expand All @@ -182,7 +132,7 @@ To utilize the OIDC protocol, follow these steps:
id-token: write
```

<div id="workflowstep2"/>
<div id="workflowstep2"></div>

2. **Pass the 'oidc-provider-name' input to the Action (Required)**: The 'oidc-provider-name' parameter designates the OIDC configuration whose one of its identity mapping should align with the generated JWT claims. This input needs to align with the 'Provider Name' value established within the OIDC configuration in the JFrog Platform.
3. **Pass the 'oidc-audience' input to the Action (Optional)**: The 'oidc-audience' input defines the intended recipients of an ID token (JWT), ensuring access is restricted to authorized recipients for the JFrog Platform. By default, it contains the URL of the GitHub repository owner. It enforces a condition, allowing only workflows within the designated repository/organization to request an access token. Read more about it [here](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-audience-value).
Expand All @@ -201,6 +151,58 @@ Example step utilizing OpenID Connect:

</details>

<details>
<summary>⚙️ Storing the connection details using single Config Token</summary>

###

1. Make sure JFrog CLI is installed on your local machine by running `jf -v`.
2. Configure the details of the JFrog platform by running `jf c add`.
3. Export the details of the JFrog platform you configured, using the server ID you chose. Do this by running `jf c export <SERVER ID>`.
4. Copy the generated Config Token to the clipboard and save it as a secret on GitHub.

To use the saved JFrog platform configuration in the workflow, all you need to do it to expose the secret to the workflow.
The secret should be exposed as an environment variable with the _JF*ENV*_ prefix.
Here's how you do this:

```yml
- uses: jfrog/setup-jfrog-cli@v4
env:
JF_ENV_1: ${{ secrets.JF_SECRET_ENV_1 }}
- run: |
# Ping the server
jf rt ping
```

As you can see in the example above, we created a secret named _JF_SECRET_ENV_1_ and exposed it to the workflow
as the _JF_ENV_1_ environment variable. That's it - the ping command will now ping the configured Artifactory server.

If you have multiple Config Tokens as secrets, you can use all of them in the workflow as follows:

```yml
- uses: jfrog/setup-jfrog-cli@v4
env:
JF_ENV_1: ${{ secrets.JF_SECRET_ENV_1 }}
JF_ENV_2: ${{ secrets.JF_SECRET_ENV_2 }}
- run: |
# Set the utilized JFrog configuration by providing the server ID (configured by the 'jf c add' command).
jf c use local-1
# Ping local-1 Artifactory server
jf rt ping
# Now use the second sever configuration exposed to the Action.
jf c use local-2
# Ping local-2 Artifactory server
jf rt ping
```

| Important: When exposing more than one JFrog configuration to the Action, you should always add the `jf c use` command to specify the server to use. |
|------------------------------------------------------------------------------------------------------------------------------------------------------|

| Important: If both Config Token(`JF_ENV_*`) and separate environment variables(`JF_URL`, ...) are provided, the default config will be the Config Token. To make the above separate environment variables as the default config use `jf c use setup-jfrog-cli-server` |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

</details>

## Setting the build name and build number when publishing build-info to Artifactory

The Action automatically sets the following environment variables:
Expand All @@ -212,9 +214,9 @@ are registered as the build artifacts.

```yml
- run: |
jf rt dl artifacts/
jf rt u aether artifacts/
jf rt bp
jf rt download "my-repo/artifacts/*" local-dir/
jf rt upload "local-dir/*" new-repo/my-artifacts/
jf rt build-publish
```

You may override the default build name and number by setting the above variables in your workflow.
Expand All @@ -238,7 +240,7 @@ It is also possible to set the latest JFrog CLI version by adding the _version_
```

| Important: Only JFrog CLI versions 1.46.4 or above are supported. |
| ----------------------------------------------------------------- |
|-------------------------------------------------------------------|

## Setting the JFrog project key

Expand Down Expand Up @@ -268,22 +270,12 @@ Here's how you do this:
env:
# JFrog platform url (for example: https://acme.jfrog.io)
JF_URL: ${{ vars.JF_URL }}
JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
# Basic authentication credentials
JF_USER: ${{ secrets.JF_USER }}
JF_PASSWORD: ${{ secrets.JF_PASSWORD }}
# JFrog platform access token (if JF_USER and JF_PASSWORD are not provided)
# JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
# Same can be achieved with a Config Token using JF_ENV_1 environment variable
# JF_ENV_1: ${{ secrets.JF_SECRET_ENV_1 }}
with:
download-repository: jfrog-cli-remote
```

- See instructions for configuring the JFrog connection details under [Storing JFrog connection details as secrets](#storing-jfrog-connection-details-as-secrets).

## JFrog Job Summary

Jobs using this GitHub action will output a summary of some of the key commands that were performed using JFrog CLI.
Expand All @@ -293,7 +285,7 @@ The summary can be viewed from the GitHub Actions run page and is enabled by def
### Preconditions
To fully leverage from the JFrog Job Summary, one should:
1. Use JFrog CLI version 2.62.0 or above.
2. Set `JF_URL` as a variable rather than a secret (see note below).
2. Set `JF_URL` as a [GitHub Variable](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/variables) rather than a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) (see note below).
3. [Collect build info](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/build-integration) and [publish](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/build-integration#publishing-build-info) it using JFrog CLI.

> **_NOTE:_** The Job Summary includes direct links to the JFrog Platform UI.
Expand Down

0 comments on commit c0bbcc1

Please sign in to comment.