# Set a trust policy

Say on a role which workloads, by the claims of their OIDC token, may assume it.

A role without a trust policy cannot be assumed by any token. The trust policy names an identity
provider and the token claims a job must carry. Replace ci-deployer with the role's name,
role-id with its id,
`org-EXAMPLE1234` with your organization's id and provider-id with the provider's id. For
how matching works, see [Web identity federation](web-identity-federation.md).

## Prerequisites

- Permission for `iam:UpdateAssumeRolePolicy` on the role. To open the role, `iam:GetRole`.
- In the console, also `iam:ListRoles` to open **Roles** (without it the list says you do not have
  permission to list roles).
- For the console's GitHub Actions template, also `iam:ListOpenIdConnectProviders`: without it
  the page lists no provider and says "No identity provider is registered yet."
- A custom role (see [Create a role](create-a-role.md)). Preset roles have no trust policy.
- The identity provider is registered (see [Add an identity provider](add-an-identity-provider.md)).

## Set the trust policy

**Console**
1. Open **Identity**, then choose **Roles**, and open ci-deployer.
2. Choose **Trust policy**.
3. Under **GitHub Actions template**, for **Match the repository by**, choose
   **ID (survives renames)** and enter the **Repository ID**, or choose **owner/name** and enter
   the **Repository**. `gh api repos/OWNER/NAME --jq .id` prints the ID.
4. For **Restrict to**, choose **branch** or **environment**, and enter the branch (`main`) or the
   GitHub environment.
5. Choose **Fill in**. The JSON appears in the editor below; change it there if you need to.
6. Choose **Save trust policy**.

The page says **Trust policy saved.** and shows the **GitHub Actions workflow** to copy (see
[Deploy from GitHub Actions](deploy-from-github-actions.md)). The template appears only when GitHub
Actions is a registered provider; for other providers, write the JSON in the editor.

**CLI**
```sh
dcloud iam roles set-trust-policy role-id --trust-policy '{
  "Version": "2024-01-01",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "rn:ews::org-EXAMPLE1234:iam:oidc-provider/provider-id" },
    "Condition": { "StringEquals": { "repository_id": "1162605513", "ref": "refs/heads/main" } }
  }]
}'
```

**API**
```http
PUT /iam/api/roles/role-id/trust-policy
{ "trustPolicy": { "Version": "2024-01-01", "Statement": [{ "Effect": "Allow", "Principal": { "Federated": "rn:ews::org-EXAMPLE1234:iam:oidc-provider/provider-id" }, "Condition": { "StringEquals": { "repository_id": "1162605513", "ref": "refs/heads/main" } } }] } }
```

**Terraform**
```hcl
resource "dcloud_iam_role" "ci_deployer" {
  name = "ci-deployer"
  trust_policy = jsonencode({
    Version = "2024-01-01"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = dcloud_iam_oidc_provider.github.rn }
      Condition = { StringEquals = { repository_id = "1162605513", ref = "refs/heads/main" } }
    }]
  })
}
```

## Result

A job whose token comes from that provider and carries every claim in the statement can exchange
it for credentials acting as the role (see [Deploy from GitHub Actions](deploy-from-github-actions.md)).
The template's two choices write:

| Match by       | Branch `main` writes                                                              |
| -------------- | --------------------------------------------------------------------------------- |
| **ID**         | `StringEquals`: `repository_id` and `ref` = `refs/heads/main`                     |
| **owner/name** | `StringEquals`: `sub` = `repo:my-org/my-app:ref:refs/heads/main` and `repository` |

With an environment, **ID** pins `environment` instead of `ref`, and **owner/name** writes
`sub` = `repo:my-org/my-app:environment:staging`. Matching by name stops working when the
repository or its owner is renamed or the repository moves, and for repositories whose tokens use
GitHub's immutable subjects.

To remove the trust policy, choose **Remove** on the same page, or send `"trustPolicy": null`.
Nobody can assume the role after that.

## If the trust policy is refused

The answer is 400 with the problems found, in `error` and, one by one, in `errors`. A document
that does not match the schema is reported first; the statement checks run only once it does.

- `Version: …` unless `Version` is exactly `2024-01-01`.
- `Statement 1: Principal.Federated is not an identity provider in this organization.`
- `Statement 1: an Allow statement must have a "sub" or "repository" … condition — …` when an
  `Allow` names neither `sub`, `repository`, `repository_id` nor `repository_owner_id`.
- `Statement 1: the "sub"/"repository" condition only uses wildcards — pin at least the owner, …`
  for example `repo:*` or `repo:*@1001/*@5005:…`.
- `The trust policy is not valid JSON.`

## Extend a GitHub Actions trust policy to Deutsche Cloud CI

A repository imported or mirrored from GitHub (see
[Import a repository](/docs/git/guide/import-a-repository)) runs its workflows on Deutsche Cloud CI,
whose tokens come from another issuer and name the repository here. `trust-ci` gives every `Allow`
statement that trusts the GitHub Actions provider a twin for Deutsche Cloud CI. The original
statements stay, so jobs on GitHub keep assuming the role.

It needs `iam:UpdateAssumeRolePolicy` on the role, a trust policy on the role, and GitHub Actions
registered as an identity provider. When the organization has no Deutsche Cloud CI provider yet, the
call registers one, which also needs `iam:CreateOpenIdConnectProvider` and counts toward the OIDC
identity providers quota; it accepts the GitHub provider's audiences and Deutsche Cloud CI's default
audience.

**Console:** not available. The console has no control for this; use the CLI or the API.
**CLI**
```sh
dcloud iam roles trust-ci role-id
```

**API**
```http
POST /iam/api/roles/role-id/trust-ci
```

**Terraform:** not available. It changes the stored trust policy once; in Terraform, write the statement for Deutsche Cloud CI into `trust_policy` yourself.

Each twin names the Deutsche Cloud CI provider and keeps the original's conditions, with these
changes:

- In `sub`, `repository`, `repository_owner`, `job_workflow_ref` and `workflow_ref`, the GitHub
  repository becomes the repository here that was imported or mirrored from it:
  `repo:acme/app:ref:refs/heads/main` becomes `repo:my-org/my-repo:ref:refs/heads/main`, where
  `my-org` is your organization and `my-repo` the repository here. In `repository_owner`, the
  GitHub owner becomes your organization. A repository from a GitHub owner whose other
  repositories came here keeps its name under your organization.
- `repository_id`, `repository_owner_id` and `actor_id` are GitHub's numbers and are left out.
- A `Sid` gets `OnThisPlatform` appended.

A statement gets no twin, and is listed in `skipped` with the reason, when a value names a GitHub
repository or owner nothing here came from (`… names a repository that is not here`), or when it
names the repository by neither `sub` nor `repository` (`… it pins the repository only by GitHub's
numeric ids`). Statements written by the template's **ID (survives renames)** choice are of that
second kind. Running it again adds no statement twice.

The answer holds `added` (how many statements were added), `skipped` and the new `trustPolicy`.
It is refused with:

- 404 `Role not found`.
- 409 `The role has no trust policy to extend`.
- 409 `The role trusts no GitHub Actions identity provider`: the organization has no GitHub Actions
  provider.
- 400 with the problems found, when the extended policy does not pass the checks above.

## Related

- [Web identity federation](web-identity-federation.md): conditions, claims and token checks.
- [Revoke role sessions](revoke-role-sessions.md)
- `iam.roles.set-trust-policy` · `dcloud iam roles set-trust-policy` · `dcloud_iam_role`
- `iam.roles.trust-ci` · `dcloud iam roles trust-ci`
