Cloud authentication from a pipeline

Overview

Deploy from a pipeline into your own AWS account with no access key stored anywhere. Gitmoap signs a short-lived token for every run, naming the repository, the branch, the commit and — where a step deploys to one — the environment; your account trusts Gitmoap as an identity provider, and the role's trust policy decides which runs may assume it. What a step receives is a credential that expires with the run and a role you can narrow to a single branch of a single repository — and there is nothing left to rotate, because there is no secret.

This replaces the pattern where a long-lived access key sits in a connection and grants whatever it grants until somebody remembers to change it. Setup is three things: register the issuer once in your account, write a trust policy, and point a connection at the role.

Before you start

How it works

The exchange, end to end

Two properties are worth stating plainly. The token grants nothing on Gitmoap — its only audience is AWS's token-exchange endpoint, and it cannot read a repository, a run or a work item. And it outlives nothing: it is signed when the run starts, held encrypted until the steps that need it are dispatched, handed to each of them as a file the AWS SDK reads, and swept away once the run reaches a terminal state. The private signing key never leaves the key-management service, so even the platform cannot export it.

The step receives four environment values it does not have to be told about — AWS_ROLE_ARN, AWS_ROLE_SESSION_NAME, AWS_WEB_IDENTITY_TOKEN_FILE and AWS_REGION — and the AWS SDK's default credential chain does the exchange with no code. Those four names are reserved: writing one as a pipeline variable or an environment variable is refused with 400, so nothing a pipeline declares can point a Gitmoap-signed token at a role you did not choose.

What the token says

Only the subject can be pinned in an IAM policy

This is the one thing that costs people an afternoon. AWS exposes rich condition keys for an OIDC provider it has written a built-in mapping for; for any other issuer it offers a fixed handful — aud, sub, amr, email and oaud — and a Gitmoap token carries only the first two. A condition written against oidc.gitmoap.com:repository_id or oidc.gitmoap.com:environment is false for every token ever issued — the statement simply never matches, and AWS answers AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity without naming the key that failed.

Everything you can enforce therefore lives in the subject, which is why the subject carries two things and no more:

The repository's id, not its path, because a policy has to keep matching after a rename or a transfer, and because a path that is freed can later be taken by an unrelated repository. The ref, because pinning a branch is the difference between "this role deploys production" and "this role deploys whatever anyone pushed". The other claims are still in the token, and a relying party that reads tokens directly can use them — they just cannot appear in an IAM condition.

The ref in the subject is always a branch. A push or a merge-request run names the branch it is building — for a merge request, that is the source branch. A tag run and a manual run with no branch given both fall back to the repository's default branch. A pattern like refs/tags/v* matches nothing.

How long the token lives

The token expires five minutes after the run's own timeout, so it outlives every step: the AWS SDK re-reads the token file and re-assumes the role each time credentials refresh, and a token shorter than the run would break a long deploy partway through. A run that names no timeout gets the default of two hours, so its token lives two hours and five minutes. Re-triggering or retrying mints a fresh token; the previous one stays valid until it expires on its own.

One token per environment

environment is a property of a step, not of a run, so a run with a staging step and a production step is minted two tokens — one carrying each environment's claims — plus one carrying no environment claim if some federated step declares none. Each step is handed the token for the environment it resolved to.

That claim comes from the platform's own resolution — walking up from the repository to find the environment, checking the environment's allowed scopes and refs, and waiting for approval where the environment requires it — never from text in the pipeline. A step that declared no environment receives a token with no environment claim, so it cannot present itself as the production step that ran beside it.

Signing keys and rotation

The key set publishes the issuer's signing key as an RSA key for signature verification, with a kid that matches the kid in the token header — which is how a relying party picks the right key out of the set. Each response carries a five-minute Cache-Control lifetime, and your cloud re-fetches on a schedule of its own on top of that.

Rotation is a platform operation and there is nothing for you to do for it: you register the issuer, not a key, so a new signing key needs no change on your side. Nor is there a certificate thumbprint to maintain — AWS validates the issuer's certificate against its own trusted authorities, so that field on an identity provider is a formality.

How to

Read the issuer address and the claim vocabulary

Do this first. The issuer value is what you register and what your trust-policy condition keys are prefixed with, and claims_supported is the complete list of claim names a token can carry — useful when you are deciding what a relying party of your own should read.

Fetch the signing keys

Your cloud fetches these on its own, so reading them by hand is a diagnostic rather than a setup step. It answers one question well: which key ids are live right now, which is what you want to know if verification started failing around a rotation.

Register Gitmoap as an identity provider in AWS

Once per AWS account, not once per repository.

Write a trust policy only your repository can satisfy

The role's trust policy is where you decide which runs are allowed in. Two conditions, both against claims AWS actually exposes:

The condition-key prefix is the issuer's host with no scheme. The repository id is the repository_id the repositories API returns — a uuid, and the same value that appears in the token's repository_id claim.

Never write a subject pattern that starts with repo:*. It grants every repository on the platform, including ones you do not own.

Point a pipeline step at the role

Create a provider connection whose authentication mode is federation, with the role to assume and, unless your calls go to eu-west-1, the region. There is no credentials block, and no secret is stored.

A connection made on a group is inherited by every repository under it. A repository's own connection displaces an inherited one only when the two share a name — the most specific scope wins for that name. Two differently-named connections for the same provider do not shadow each other: they are both candidates, and a step that names neither leaves the run unable to choose, so it refuses to start rather than guessing. Name the connection on the step whenever more than one is in scope.

The full walkthrough of the connection form and its refusals is in Using providers; the part that matters here is that the authentication mode is fixed when the connection is created, so moving from stored keys to federation means creating the new connection and deleting the old one.

Move a connection to a different role

The mode is fixed, but the target is not. Update the federation connection with a new role ARN — or a new region — and the next run picks it up; runs already in flight keep the role they were dispatched with. This is how you promote a role, split one role into two, or move to a different AWS account without touching the pipeline.

Give each environment its own role

Since IAM cannot test the environment claim, separate roles are how you keep staging out of production. Create one role per environment, with its own trust policy and its own permissions, and one connection per role. Then name the right connection on each step — the staging step takes the staging connection, the production step takes the production one.

Pin the branch in each trust policy as well. A production role that trusts only refs/heads/main is protected even if somebody points the wrong connection at the wrong step.

Check that a run really federated

The step's log says which way it authenticated before it makes a single AWS call. A federated step prints a line naming web-identity federation, then the role ARN, the session name, the token file with whether it exists, and the region. A step using stored keys prints Auth: static credentials instead — so if you see that line, your federation connection is not the one the step resolved. If the federation lines are there but AWS_ROLE_ARN prints <unset>, the step resolved no connection at all and nothing pointed it at a role.

To see what the repository resolves before you run anything, read its resolved provider connections — GET /repositories/{repo_id}/resolved-provider-connections — which walks the repository and its parent groups and returns the connection each provider ends up with.

In your own account, the assumed session is named gitmoap-pipeline-<run id>, capped at the 64 characters AWS allows for a session name. That is the string to search CloudTrail for when you want to prove which run made a given API call.

Move a pipeline off stored access keys

Take a role away from a pipeline

Deleting the connection stops any future run from being handed the role. It does not reach into a run already in flight, whose credentials live until they expire, and it does not change anything in your account — the role and its trust policy are still there, and anything else satisfying that trust policy still gets in. To cut it off completely, tighten or delete the trust policy in AWS as well.

Reference

Both documents are public: no token, no sign-in, no scope. Each response carries a five-minute Cache-Control lifetime, and your cloud fetches them on its own schedule.

The endpoints answer 501 when Gitmoap's token issuer is unavailable. That is a service-wide fault rather than anything about your account, and federation is unavailable for everyone until it is fixed.

Troubleshooting

FAQ

Related