Service account sign-ins

A service account signs in in one of two ways:

• A GitHub Actions workflow that it trusts. The trust is for one repository and one branch, tag or environment. GitHub vouches for each run, so there is no secret to keep.
• An API key, where GitHub is not available.

source-coop service-account sign-in add my-org--nightly-sync --github my-org/data --branch main
source-coop service-account sign-in add my-org--nightly-sync --github my-org/data --environment production
source-coop service-account sign-in add my-org--nightly-sync --subject repo:my-org/data:ref:refs/tags/v1
source-coop service-account sign-in remove my-org--nightly-sync repo:my-org/data:ref:refs/heads/main
source-coop service-account sign-in remove my-org--nightly-sync -i   # select a sign-in

• --github OWNER/REPO with --branch, --tag or --environment makes the subject that GitHub's tokens contain, such as repo:OWNER/REPO:ref:refs/heads/main.
• --subject takes a subject as it is.

The CLI asks GitHub how the repository's tokens name it, as the web UI does. Some repositories use IDs (owner@123/repo@456), which never match owner/repo. For a private repository, set GH_TOKEN (or GITHUB_TOKEN). If GitHub does not answer, the CLI tells you how to find the name.

At a terminal, without these flags, sign-in add asks for the repository and the runs to trust. Then it shows the condition and asks you to confirm.

API keys are for places without GitHub's tokens, such as a cron job on a cluster.

• Each key has a label that tells where it is used. Use it to find the key to revoke.
• A key expires after 30 days, 90 days (default), one year, never, or on a date (at midnight UTC).

source-coop service-account sign-in add my-org--nightly-sync --key "HPC cron job" --expires 1y --out ~/.source-coop/nightly.key
key=$(source-coop service-account sign-in add my-org--nightly-sync --key "HPC cron job")   # piped: only the key on stdout
source-coop service-account sign-in edit my-org--nightly-sync key:a1B2c3 --expires never      # a new expiry, from now
source-coop service-account sign-in remove my-org--nightly-sync key:a1B2c3                    # revoke it; asks you to type key:a1B2c3

The CLI shows a key one time only, when it issues the key:

• --out PATH writes the key to a new file that only you can read. AWS tools read the key from a file.
• If a file is already at that path, the CLI does not overwrite it. It shows the key. It also shows the key if it cannot write the file.
• When piped, stdout gets only the key.
• On a terminal, the CLI asks for a file name. Press Enter to show the key instead.

view lists each key by its label and its last six characters, such as key:a1B2c3. sign-in edit and sign-in remove use this name. view also shows when the key was last used and when it expires. It shows revoked and expired keys dimmed. You cannot restore a revoked key.

At a terminal, without flags, sign-in add asks if you want a workflow or a key. sign-in edit -i and sign-in remove -i let you select one.

If a key leaks, anyone with the key can revoke it, without signing in. The command reads the key from stdin, so the key is not in your shell history:

source-coop service-account sign-in revoke-key < leaked-key-file

Use a service account

Workflows and scripts sign in with standard AWS tools, not with this CLI. usage prints what they need, as the web UI does:

source-coop service-account usage my-org--nightly-sync --subject repo:my-org/data:ref:refs/heads/main \
    > .github/workflows/source-coop.yml   # a workflow that uses aws-actions/configure-aws-credentials
source-coop service-account usage my-org--nightly-sync --key   # the AWS_* variables for a key in a file

At a terminal, without --subject or --key, usage asks which sign-in to show.