Osy#betaRun it on Osyrin: osyrin.com

Reference / Local

Deploying from CI with a deploy token

osyrin app token create <name> [--days <days>] [--app <slug>] [--server <url>] [--json] · osyrin app token list · osyrin app token revoke <id> · OSYRIN_TOKEN=<token> · OSYRIN_TOKEN_FILE=<path> · Security.IssueJwt(userId, email, notAfter)

A deploy token is the credential a CI job or a script deploys ONE application with and sets that application's secrets with — nothing else. An owner or admin of the application's organization makes one (`osyrin app token create`, or the app's Deploy tokens page); it is shown once, kept only as a hash, expires on the date you chose and can be revoked at once. Hand it to `osy deploy` and `osyrin app secret set` in `OSYRIN_TOKEN`.

preview1 example compiled by CIlocalclideployci

Summary#

A CI job should not sign in as you. A deploy token is made for one application: it deploys that application and sets that application's secrets, and it can do nothing else — it reads none of its data, reaches no other application (not even one of the same organization), and makes no other token. After a deploy it reads one more thing, so osy deploy can say which workflow runs are still on an older version: how many runs there are per workflow, version and state — never a run itself, its item or its error. To see the runs, sign in as a person and run osyrin app workflow-runs.

Signature#

osyrin app token create <name> [--days <days>] [--app <slug>] [--server <url>] [--json]
osyrin app token list [--app <slug>] [--server <url>] [--json]
osyrin app token revoke <id> [--app <slug>] [--server <url>]
OSYRIN_TOKEN=<token>          # or OSYRIN_TOKEN_FILE=<path of a file holding it>

Description#

Making one. osyrin app token create "GitHub Actions on main" --days 90 prints the token — osd_ and 43 characters — once. Store it in your CI's secrets at once: the platform keeps only its hash, and nobody can show it again. A token lasts from 1 to 365 days (90 unless you say). Only an owner or admin of the application's organization makes, lists and revokes tokens; the same is on the application's Deploy tokens page in the console.

Using one. Set OSYRIN_TOKEN (or OSYRIN_TOKEN_FILE, the path of a mounted secret) in the job's environment, and run osy deploy --env prod --server <url> or osyrin app secret set --server <url> as usual. The CLI trades the token once per run for a short ticket from the named server, and acts as the token. The server comes from --server or the project's osyrin.json only: with neither, the command refuses and sends the token nowhere — not to the installation the computer is signed in to, nor to a default. Once traded, the CLI acts as the token — its deploys and secret writes are recorded under the token's own name, never under a person's. It never falls back to a stored sign-in: a token the server refuses stops the command with the server's reason. The token is read from the environment only, never from a command-line flag, because a process's arguments are visible to every other process on the machine. A machine ticket handed in by OSYRIN_ADMIN_TOKEN wins over it.

What the job waits for. In CI osy deploy prints one line per step and per stage the platform reports, with its time, and waits for the platform the token was traded with to say the version is served — at most 45 minutes, or what --wait says. Its exit code is what a job checks: 0 served, 1 refused or failed (the stage and the reason are printed), 2 the wait ended first and the deploy goes on on the platform (osy status shows how it ends). After served it prints one more line about the app's public address — whether it answers with the deployed version, or does not point at this installation yet. The token is never sent to that address, and that line never changes the exit code.

Ending one. A token past its expiry signs nobody in, and the ticket it was traded for ends at the same moment. osyrin app token revoke <id> (the id is in list) ends it at once: it signs nothing in again, and a ticket it already holds loses its power on the next request.

In your own app: a ticket with an end. The same cap is open to an app's own sign-in code. Security.IssueJwt(userId, email, notAfter) mints a ticket that expires at notAfter at the latest, and no renewal of it, and no browser session made from it, lasts past that moment. Use it when the credential a sign-in trades has an end date of its own — an invitation, a time-boxed access key. A notAfter already in the past is refused.

[Role] enum KeyRole { Authenticator }
[Principal] entity Holder {
  [Unique, MaxLength(200)] string Email;
  security { allow read when IsAuthenticator; }          // the sign-in flow alone reads the holder
}
[RoleGrant] entity RoleGrant { [Required] Holder Member; [Required] KeyRole Role; }
entity AccessKey {
  [Required, MaxLength(100)] string KeyHash; [Required] DateTime EndsAt; Holder Holder;
  security { allow read when IsAuthenticator; }          // …and the key it looks up
}
policy IsAuthenticator => RoleGrant.Any(g => g.Member == user && g.Role == KeyRole.Authenticator);

[AuthMethod]
string SignInWithAccessKey(string key) {
  var access = AccessKey.Include(a => a.Holder).Where(a => a.KeyHash == Security.HashApiKey(key)).FirstOrDefault();
  if (access == null || access.EndsAt <= DateTime.UtcNow) { throw new ValidationException("That key is not valid."); }
  return Security.IssueJwt(access.Holder.Id, access.Holder.Email, access.EndsAt);   // never good past the key's end
}

app.AuthBootstrap = new AuthBootstrap { Role = KeyRole.Authenticator, Login = SignInWithAccessKey };

Examples#

osyrin app token create "GitHub Actions on main" --days 90   # printed once: store it in the CI's secrets now
osyrin app token list                                         # name, who made it, expiry, last use — never the token
OSYRIN_TOKEN="$DEPLOY_TOKEN" osy deploy --env prod --server https://osyrin.app
osyrin app token revoke 3f2c…                                 # ends it, and the ticket it holds, at once

See also#

Deploying your app to an environment — what osy deploy does once it is signed in.

Giving a secret its value — osyrin app secret set, which a deploy token may run for its application.

Signing in to Osyrin — signing in as yourself, for everything a token may not do.

Related

Deploying your app to an environment

Builds your app on this machine and hands it to the zone one of its organization's environments runs on — `osy deploy…

Giving a secret its value

Declaring `app.Secrets` names a secret; it does not give it a value, and an app cannot run until something does. `osy…

Signing in to Osyrin

`osyrin login` signs you in to an Osyrin in your browser, on Osyrin's own sign-in page, and keeps the sign-in where…

[Actor] — a principal that code may run as

A class marked `[Actor]` declares a principal that code may run as: a robot, a nightly job, an integration, a digital…