[Yandex Cloud documentation](../../index.md) > [Yandex Identity and Access Management](../index.md) > [Tutorials](index.md) > Integrations of workload identity federations > GitHub

# Getting Yandex Lockbox secret value on the GitHub side

[Workload identity federations](../concepts/workload-identity.md) allow you to configure a link between external systems and Yandex Cloud via the [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) protocol. This allows external systems to perform actions with Yandex Cloud resources under IAM [service accounts](../concepts/users/service-accounts.md) without using [authorized keys](../concepts/authorization/key.md). This is a more secure method that minimizes the risk of credential leakage and the possibility of unauthorized access.

This tutorial shows you as an example how to get the [Yandex Lockbox](../../lockbox/index.md) [secret](../../lockbox/concepts/secret.md) value from the GitHub side under a Yandex Cloud service account. Similarly, you can perform any action via the Yandex Cloud [CLI](../../cli/quickstart.md), [API](../../api-design-guide/index.md), or [Terraform](../../terraform/index.md).

To get the Yandex Lockbox secret value under a GitHub account:

1. [Create a repository in GitHub](#create-github-repo).
1. [Get your cloud ready](#prepare-cloud).
1. [Configure a GitHub Actions script](#github-actions-workflow).

If you no longer need the resources you created, [delete them](#clear-out).

## Create a repository in GitHub {#create-github-repo}

[Create](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository) a new GitHub repository or use an existing one where you have permissions to view and run GitHub Actions.

## Get your cloud ready {#prepare-cloud}

Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md).

### Required paid resources {#paid-resources}

The infrastructure support cost includes a fee for storing a [secret](../../lockbox/concepts/secret.md) and requests to it (see [Yandex Lockbox pricing](../../lockbox/pricing.md)).

### Create a workload identity federation {#federation-iam-accounts}

{% list tabs group=instructions %}

- Management console {#console}

   1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a workload identity federation.
   1. Navigate to **Identity and Access Management**.
   1. In the left-hand panel, select ![cpus](../../_assets/console-icons/cpus.svg) **Workload identity federations**.
   1. Click **Create federation**.
   1. In the **Issuer value (iss)** field, enter the OIDC provider's URL: `https://token.actions.githubusercontent.com`.
   1. In the **Acceptable Audience values (AUD)** field, enter the token recipient: `https://github.com/<github_user_name>`.
   1. In the **JWKS address** field, enter the URL of the public key list: `https://token.actions.githubusercontent.com/.well-known/jwks`.
   1. In the **Name** field, enter a name for the federation, e.g., `test-iam-federation`.
   1. Click **Create**.

{% endlist %}

### Create a custom secret

{% list tabs group=instructions %}

- Management console {#console}

   1. In the [management console](https://console.yandex.cloud), select the folder where you want to create your secret.
   1. Navigate to **Lockbox**.
   1. Click **Create secret**.
   1. In the **Name** field, enter a name for the secret: `MY_SECRET`.
   1. Select **Secret type** `Custom`.
   1. In the **Key** field, enter a non-secret ID, e.g., `secret`.
   1. In the **Value** field, enter the confidential data you want to store.
   1. Click **Create**.

{% endlist %}

### Create a service account.

1. Create a service account:

   {% list tabs group=instructions %}

   - Management console {#console}

      1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a service account.
      1. Navigate to **Identity and Access Management**.
      1. Click **Create service account**.
      1. Enter a name for the service account, e.g., `sa-lockbox`.
      1. Click **Create**.

   {% endlist %}

1. Assign the `lockbox.payloadViewer` [role](../concepts/access-control/roles.md) for the folder to the service account: 

   {% list tabs group=instructions %}

   - Management console {#console}

      1. On the management console [home page](https://console.yandex.cloud), select a folder.
      1. Navigate to the **Access bindings** tab.
      1. Find the `sa-lockbox` account in the list and click ![image](../../_assets/console-icons/ellipsis.svg).
      1. Click **Edit roles**.
      1. In the dialog that opens, click ![image](../../_assets/console-icons/plus.svg) **Add role** and select the `lockbox.payloadViewer` role.

   {% endlist %}

### Link the service account to the Federation

{% list tabs group=instructions %}

- Management console {#console}

   1. In the [management console](https://console.yandex.cloud), select the folder the service account was created in.
   1. Navigate to **Identity and Access Management**.
   1. In the list of service accounts, select `sa-lockbox`.
   1. In the top panel, click ![image](../../_assets/console-icons/cpus.svg) **Link to federation**.
   1. In the **Workload identity federation** field, select the federation you created earlier.
   1. In the **Subject value (sub)** field, specify the external account ID: `repo:<github_user_name>/<github_repository_name>:ref:refs/heads/main`.
   1. Click **Link**.

{% endlist %}

## Configure a GitHub Actions script {#github-actions-workflow}

1. Clone your repository if you have not done so already:

   ```bash
   git clone <repository_URL>
   ```

1. In a local copy of your repository, create a file named `blank.yml` in the `.github/workflows` directory.
1. Insert the following code into the `blank.yml` file that will get the value of the Yandex Lockbox secret:

   ```yaml
   name: CI

   permissions:
     id-token: write # Required to request a JWT token

   # Controls when the workflow will run
   on:
     # Runs a script on push or pull request in the _main_ branch
     push:
       branches: [ "main" ]
     pull_request:
       branches: [ "main" ]
   
     # Allows running a script manually in the Actions tab
     workflow_dispatch:

   jobs:
     job:
       runs-on: ubuntu-latest
       steps:
       - name: Install OIDC Client from Core Package
         run: npm install @actions/core @actions/http-client
       # Getting the workflow task token
       - name: Get Id Token
         uses: actions/github-script@v7
         id: tokenid
         with:
           script: |
             const coredemo = require('@actions/core')
             let id_token = await coredemo.getIDToken()
             coredemo.setOutput('id_token', id_token)
       # Exchanging the workflow task token for an IAM token of a service account in Yandex Cloud
       - name: GetIAMToken
         run: |
           SA_ID="<service_account_ID>"
           IAMTOKEN=$(curl -sH "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&requested_token_type=urn:ietf:params:oauth:token-type:access_token&audience=$SA_ID&subject_token=$not_var{{steps.tokenid.outputs.id_token}}&subject_token_type=urn:ietf:params:oauth:token-type:id_token" -X POST https://auth.yandex.cloud/oauth/token | jq -r '.access_token')
           echo "IAMToken=${IAMTOKEN}" >> $GITHUB_OUTPUT
         id: IAMtoken
       # Requesting secret value via the API using an IAM token in Yandex Cloud
       - name: GetLockboxPayload
         run: |
           SECRET_ID="<secret_ID>"
           SECRET_DATA=$(curl -sH "Authorization: Bearer $not_var{{steps.IAMtoken.outputs.IAMTOKEN}}" https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/$SECRET_ID/payload)
           echo "SECRET_DATA=${SECRET_DATA}" >> $GITHUB_OUTPUT
         id: getlockboxpayload
   ```

   Where:
   * `SA_ID`: Service account ID.
   * `SECRET_ID`: Custom secret ID.

1. Save the file and submit the changes to the remote repository:

   ```bash
   git add . && git commit -m "Added blank.yml" && git push
   ```

   Once you submit the code to the repository, the workflow will begin. You can see the script execution result logged on your repository's `Actions` tab:

   ```json
   {
   "entries": [
   {
      "key": "secret",
      "textValue": "67cH2£?pO********"
   }
   ],
   "versionId": "e6q8isknpcp7********"
   }
   ```

## Delete the resources you created {#clear-out}

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

* [Yandex Lockbox](../../lockbox/operations/secret-delete.md) secret
* [Service account](../operations/sa/delete.md)

## Useful links {#see-also}

* [Secure storage of GitLab CI passwords as Yandex Lockbox secrets](../../tutorials/security/gitlab-lockbox-integration.md)