Sign in from GitHub Actions

A trust lets a GitHub Actions workflow sign in to Edka with the OIDC token GitHub gives its job, so the repository stores no Edka secret. The trust names the repository, the branches, tags or environments its jobs run in, and one custom app. The workflow can publish new versions of that app with edka apps publish and move its installed instances to a version with edka apps update. Edka refuses every other request.

Prerequisites

• The Admin role in the organization, to create a trust.
• A GitHub repository with the package of the custom app, and the app’s slug, the slug in its template.yaml.
• For updates, the app installed on the clusters the workflow updates.

Create a trust

In the console, open Settings, then Organization. Under Trusted workflows, fill in:

• Name, to recognize the trust, such as Release workflow.
• Repository, as owner/name.
• Branches and tags the jobs run on, such as refs/heads/main. A ref ending in * matches every ref that starts with it: refs/tags/v* matches each tag that starts with v.
• Environments, when the jobs run in a GitHub environment. With both refs and environments, a job has to match one of each.
• Workflow file, to accept the jobs of one workflow only, such as .github/workflows/release.yml.
• Custom app, the slug of the app.
• Publish new versions of the app and Update its installed instances, and the clusters whose instances the workflow updates. With no cluster checked, it updates the instances on every cluster.

Select Save trust. The console shows the trust’s ID and the job settings that use it. In an organization with passkey checks, saving or deleting a trust asks for one.

From the CLI:

edka trusts create release \
  --repository acme/api \
  --ref refs/heads/main \
  --workflow .github/workflows/release.yml \
  --app api \
  --clusters production

Edka reads the repository’s numeric ID and its owner’s ID from GitHub, through the organization’s GitHub integration, or as a public repository. For a repository Edka can’t see, add --repository-id and --owner-id. This command prints both:

gh api repos/acme/api --jq '.id, .owner.id'

Use the trust in a workflow

Give the job id-token: write, set EDKA_TRUST to the trust’s ID, and run the CLI:

name: Release
on:
    push:
        branches: [main]

jobs:
    release:
        runs-on: ubuntu-latest
        permissions:
            contents: read
            id-token: write
        env:
            EDKA_TRUST: 7d1e4c62-3c4b-4b8e-9b1f-0a4f2c1d9e01
        steps:
            - uses: actions/checkout@v4
            - name: Install the Edka CLI
              run: |
                  curl -fsSL https://edka.io/install.sh | sh
                  echo "$HOME/.local/bin" >> "$GITHUB_PATH"
            - run: edka apps publish ./api
            - run: edka apps update api --cluster production --yes --wait

Each edka command asks GitHub for an OIDC token whose audience is the Edka API’s origin, https://api.edka.io, and Edka exchanges it for an access token of the trust. The access token lasts 15 minutes. The CLI exchanges a new GitHub token two minutes before the last one expires, so --wait keeps working for as long as the update takes. Nothing is written to disk.

A trust’s ID is not a secret: only a job of the trusted repository, on a trusted ref, gets a GitHub token that Edka accepts with it. --trust <id> works like EDKA_TRUST.

Check that it worked

The job log shows each step:

✓ Published api 1.4.0
It is in the catalog of every cluster in your organization.
Version 1.4.0 changes:
  - Image ghcr.io/acme/api: 1.3.0 to 1.4.0
✓ api runs 1.4.0

edka whoami prints the trust, its app and the repository in place of a person. The console shows when each trust was last used.

What a trust accepts

Edka accepts a GitHub token when:

• GitHub signed it, its issuer is https://token.actions.githubusercontent.com, its audience is the API’s origin, and it has not expired. Edka accepts each token once.
• Its repository ID and owner ID are the trust’s. A repository deleted and created again under the same name has another ID, and its jobs are refused.
• Its repository name is the trust’s. After a rename, update the trust’s repository.
• Its ref is a branch or a tag. A pull request’s job is refused, even in an environment the trust names.
• Its ref matches one of the trust’s branches and tags, when the trust names any.
• Its environment is one of the trust’s, when the trust names any.
• Its workflow file is the trust’s, when the trust names one.

What a trust can do

A trust’s token reaches the requests of edka apps publish and edka apps update, for the trust’s app only:

• Publishing a package with another slug is refused.
• A cluster list shows only the clusters with an instance the trust updates, and an app list only those instances.
• An update changes the version and nothing else.
• A trust never passes a passkey check, so actions behind one stay with people.

Deleting a trust stops its workflows at once: the access tokens they hold stop working on the next request. Changing a trust does the same to every token issued under its earlier settings.

Troubleshooting

The job can’t request a token

signing in with a trust needs a GitHub Actions job with `permissions: id-token: write`

Add id-token: write to the job’s permissions. A job that sets permissions gets only the ones it lists.

The trust refuses the job

This trust doesn't accept jobs on refs/heads/feature.

The job runs on a ref the trust doesn’t name. Add the ref to the trust, or run the job on a trusted branch or tag. This trust accepts only jobs that run in an environment. means the trust names environments and the job has no environment:. A trust doesn't accept jobs on refs/pull/12/merge, only branches and tags. means a pull request started the job; run it on a branch or a tag instead.

The repository changed

The token's repository is not the one this trust names.

The repository’s ID or its owner’s ID differs from the trust’s, as after a transfer, or after the repository was deleted and created again. Create a trust for the repository as it is now. After a rename, Edka answers The repository is now acme/api-v2. Update the trust's repository name.

A command is refused

The trust Release workflow does not allow this request.

The command is outside what the trust allows, such as edka deployments list, or an update with a trust that only publishes. Run it as a person. This trust publishes api only, and the package is web. means the package’s slug is not the trust’s app.

An Edka instance of your own

Set EDKA_API_URL in the job to the instance’s API address. The audience of the GitHub token follows it.