codeberg4s/com.worxbend.codeberg4s/com.worxbend.codeberg4s.repositories/com.worxbend.codeberg4s.repositories.actions

com.worxbend.codeberg4s.repositories.actions

package com.worxbend.codeberg4s.repositories.actions

Members list

Packages

Type members

Classlikes

A file bundle a workflow run uploaded, as the artifact endpoints report it.

'''Derived from spec/swagger.v1.json's ActionArtifact definition, not from a captured response.''' No golden fixture exists for this group — the harvest that produced modules/codec/test/resources/golden was anonymous, and every Actions endpoint requires a token — so the field set here is the spec's and the nullability is the conservative reading docs/HAZARDS.md §1 mandates: everything the domain can live without is optional.

==Downloading==

GET /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip is implemented, on com.worxbend.codeberg4s.repositories.actions.ActionDownloadApi — reached as client.downloads. It holds the whole archive in memory, because nothing in this library streams, so archiveDownloadUrl remains the route for an archive too large to want in the heap: hand it to an HTTP client that can stream bytes. Note that the URL is authenticated exactly like the API is, so the caller's own client must send the same credentials.

Value parameters

archiveDownloadUrl: where the ZIP lives — see the downloading note above
expiresAt: when the bytes are removed, absent when the instance did not report a retention window
id: the identifier the artifact endpoints address this artifact by
isExpired: whether the artifact has passed its retention window. An expired artifact is still listed and still readable as metadata; only its bytes are gone
name: the name the workflow uploaded it under; not unique within a run, and not unique within a repository
runId: the run that produced it
sizeInBytes: the total size of the archive, absent when the instance did not report it

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

One execution of a workflow, triggered by an event on a repository.

'''Derived from spec/swagger.v1.json's ActionRun definition, not from a captured response.''' See ActionArtifact for why no fixture backs this group, and docs/HAZARDS.md §1 for why every field the domain can live without is therefore optional.

==Two numbers, and only one of them addresses the run==

id is what /repos/{owner}/{repo}/actions/runs/{run_id} takes. indexInRepo is the per-repository counter the web UI shows and the run listing filters on with run_number. Both are int64 on the wire; only the first is an addressable identifier, which is why only the first has a type.

==Two event fields, and they answer different questions==

event is the webhook event that fired — push, pull_request, workflow_dispatch. triggerEvent is the entry from the workflow's own on: configuration that matched it. They usually agree and are not required to.

Value parameters

approvedBy: the numeric id of the account that released a held run; absent, and 0 on the wire, when nobody did
commitSha: the commit the run executed against, absent when the instance sent something that is not an object id
duration: how long the run took, as the instance measured it. Forgejo sends a Go time.Duration, that is a nanosecond count, which is why this is a scala.concurrent.duration.FiniteDuration and not a number of seconds
isForkPullRequest: whether the run was triggered from a fork, which is what makes needApproval meaningful
isRefDeleted: whether the branch or tag the run ran on has since been deleted
needApproval: whether the run is held until a maintainer approves it
prettyRef: the branch or tag as a human reads it, for example main rather than refs/heads/main
repository: which repository the run belongs to, projected from the embedded repository object down to its slug. Absent rather than failing when that object cannot name an addressable repository
scheduleId: the cron entry that started the run, for a scheduled trigger only
startedAt: when a runner picked the run up, absent while it is still queued
status: where the run is; absent when the instance sent a value outside the enumerated set, per ActionStatus.parse
stoppedAt: when the run finished, absent while it is still going
triggerUser: the account whose action started the run, absent for a schedule or an instance-initiated run
workflowId: the workflow file the run came from — the same string com.worxbend.codeberg4s.repositories.actions's dispatch endpoint takes as {workflowfilename}

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

One job of a run — a single jobs: entry of the workflow file, executed on one runner.

'''Derived from spec/swagger.v1.json's ActionRunJob definition, not from a captured response'''; see ActionArtifact for why.

==Labels are strings here, on purpose==

runsOn is a Vector[String] rather than a Vector[RunnerLabel]. RunnerLabel exists to keep a comma out of the '''filter''' that joins labels with commas; applying it to a value read back from the instance would mean dropping a label Forgejo genuinely holds because this library dislikes its spelling. Reading is lenient, filtering is strict.

Value parameters

attempt: how many times the job has been executed, counting the current execution. This is the value the job-logs endpoint takes as JobAttempt
handle: an opaque identifier for one attempt of one job, which the instance uses to correlate logs
id: the identifier the job-logs endpoint addresses this job by
needs: the names of the jobs this one waits for, as the workflow file spells them
ownerId: the numeric id of the account owning the repository; 0 on the wire, and absent here, for a repository-owned job
repoId: the numeric id of the repository the job ran for
runId: the run this job belongs to
runsOn: the runner labels the job requires — see the note above
status: where the job is; absent when the instance sent a value outside the enumerated set
taskId: the runner task that most recently executed the job. Not a JobId, and no endpoint here accepts it

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

The filters of GET /repos/{owner}/{repo}/actions/runs.

'''Only what the caller set is sent.''' An absent filter is not the same request as an empty one: omitting status asks for every run, and sending status= is a request Forgejo has no reading of. Nothing here has a default to fall back on, which is why ActionRunQuery.Empty renders to no parameters at all.

ActionRunQuery.Empty
 .triggeredBy("push")
 .withStatus(ActionStatus.Failure)
 .onRef("refs/heads/main")

Value parameters

events: which webhook events to include — push, pull_request, workflow_dispatch. Sent as a repeated query parameter, one per event, because the spec declares it as an array
headSha: only runs against this commit
ref: only runs involving this Git reference, for example refs/heads/main
runNumber: the per-repository counter of one run — ActionRun.indexInRepo, '''not''' RunId
statuses: which lifecycle states to include, likewise repeated. ActionStatus rather than String so a typo is a compile error instead of an empty page
workflowId: only runs of this workflow file

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ActionRunQuery.type

A machine registered to execute this repository's workflows.

'''Derived from spec/swagger.v1.json's ActionRunner definition, not from a captured response'''; see ActionArtifact for why.

==Which identifier addresses it==

The wire object carries a numeric id and a string uuid, and the path parameter is declared type: string. This model exposes id as a RunnerId built from the numeric id, because that is the value the spec's own description ("ID of the runner") points at, and keeps uuid beside it so a caller who needs the other spelling has it. See RunnerId for the full argument.

Value parameters

id: what GET and DELETE of /repos/{owner}/{repo}/actions/runners/{runner_id} are given
isEphemeral: whether the runner de-registers itself after a single job
labels: what the runner advertises, which is what a job's runs-on matches against. Plain strings for the reason ActionRunJob.runsOn gives
name: the operator's label for the machine. '''Not unique''' — the spec says so outright — so it must not be used to tell two runners apart
ownerId: the account this runner belongs to; 0 on the wire, and absent here, when the runner belongs to a repository
repoId: the repository this runner belongs to; 0 on the wire, and absent here, when it belongs to a user or an organisation
status: whether the runner is reachable and busy; absent when the instance sent a value outside the enumerated set
uuid: the runner's self-assigned identifier, reported by the runner binary at registration

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

An Actions secret, as much of one as any client is ever allowed to see.

==There is no value here, and that is the whole design==

Forgejo's Secret model has exactly two properties, name and created_at. The material is write-only: it goes in through PUT /repos/{owner}/{repo}/actions/secrets/{secretname} as a SecretValue and never comes back out, from this endpoint or any other. Modelling that faithfully means this type has no value field at all — not an Option[SecretValue] that is always None, which would invite a caller to believe some other call might fill it in, and not a String that would be empty for reasons the caller has to look up.

A caller who needs to know what a secret contains has to hold that knowledge outside the forge. That is not a limitation of this library; it is the point of a secret store.

'''Derived from spec/swagger.v1.json's Secret definition, not from a captured response'''; see ActionArtifact for why.

Value parameters

createdAt: when the secret was first set. Forgejo reports no modification time, so a secret that has been rewritten looks exactly like one that has not
name: what addresses the secret. Forgejo upper-cases names, so this is usually not the spelling the caller wrote — see SecretName

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: enum
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: ActionStatus.type

Where a run, a job or a runner task is in its lifecycle.

'''A closed set, and the spec says which one.''' Unlike most Forgejo string fields, this one is enumerated: spec/swagger.v1.json declares enum: [unknown, waiting, running, success, failure, cancelled, skipped, blocked] on the status filter of both GET /repos/{owner}/{repo}/actions/runs and GET /repos/{owner}/{repo}/actions/tasks. The status '''field''' of ActionRun, ActionRunJob and ActionTask is declared as a bare type: string, but it is the same value out of the same Go type, so the same eight cases describe it.

Forgejo merges what GitHub splits into a status and a conclusion: running is a status, success is a conclusion, and both arrive in this one field. There is therefore no separate conclusion type in this library, and ActionStatus.isFinished is how a caller asks the question a conclusion would answer.

Note that unknown is a real value the server sends, not this library's fallback for an unrecognised one — see ActionStatus.parse.

Attributes

Companion: object
Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

One unit of work a runner executed, as GET /repos/{owner}/{repo}/actions/tasks reports it.

'''A task is not a run and not a job.''' Forgejo's task listing is the flattened, runner-side view: one entry per execution, carrying the workflow file, the branch and the commit it ran against. A ActionRun groups tasks by trigger and an ActionRunJob groups them by workflow job. The three overlap heavily and are addressed by different endpoints, which is why they are three types.

'''Derived from spec/swagger.v1.json's ActionTask definition, not from a captured response'''; see ActionArtifact for why.

Value parameters

displayTitle: the title the web UI shows, usually the triggering commit's subject
headBranch: the branch the task ran against, as a human reads it
headSha: the commit the task ran against, absent when the instance sent something that is not an object id
id: the task's identifier; no endpoint in this group accepts it, and it exists so it cannot be confused with a RunId or a JobId
runNumber: the per-repository counter of the run this task belongs to — the same number as com.worxbend.codeberg4s.repositories.actions.ActionRun.indexInRepo, and not an addressable identifier
runStartedAt: when execution began, absent while the task is still queued
status: where the task is; absent when the instance sent a value outside the enumerated set
workflowId: the workflow file the task came from

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

The filters of GET /repos/{owner}/{repo}/actions/tasks.

The task listing takes exactly one filter, and it is the same enumerated status the run listing takes. As with ActionRunQuery, only what the caller set is sent: ActionTaskQuery.Empty renders to no parameters.

Value parameters

statuses: which lifecycle states to include, sent as a repeated query parameter because the spec declares it as an array

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ActionTaskQuery.type

An Actions variable: named configuration a workflow reads, and which the API '''does''' hand back.

The counterpart to ActionSecret, and the contrast is the point. A variable's value is returned by GET /repos/{owner}/{repo}/actions/variables/{variablename} and by the listing, because a variable is configuration, not a credential. That is why value is a plain String here while ActionSecret has no value field at all — and why putting a credential in a variable makes it readable by anyone who can read the repository's Actions configuration.

'''Derived from spec/swagger.v1.json's ActionVariable definition, not from a captured response'''; see ActionArtifact for why.

Value parameters

name: what addresses the variable. Forgejo upper-cases names, as it does for secrets
ownerId: the account the variable belongs to; 0 on the wire, and absent here, for a repository-level variable
repoId: the repository the variable belongs to; 0 on the wire, and absent here, for an owner-level variable
value: the variable's content, verbatim. The empty string is a legitimate value and is preserved

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ArtifactId.type

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ArtifactQuery.type

The filter both artifact listings take: a repository's artifacts, and one run's.

Forgejo matches name exactly, not as a prefix or a pattern, and artifact names are not unique — a run that uploads the same name from two jobs produces two artifacts — so this narrows a listing rather than identifying anything.

As with ActionRunQuery, only what the caller set is sent: ArtifactQuery.Empty renders to no parameters.

Value parameters

name: the artifact name to match exactly, absent to list them all

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: CreateVariable.type

What POST /repos/{owner}/{repo}/actions/variables/{variablename} is told.

The name is not part of the command: it is a path segment, and a VariableName the caller has already validated. All that is left is the value.

A separate type from UpdateVariable even though the payloads look alike, because they are not the same request: creating cannot rename, and the field the two send differs in nothing but its meaning. Collapsing them into one type would mean a renamedTo that is silently dropped on creation — the kind of quiet no-op this codebase does not ship.

Value parameters

value: the variable's content, sent verbatim. The empty string is a legitimate value, so nothing here rejects it; Forgejo normalises line endings to LF, and a caller who needs CRLF preserved must Base64-encode the value themselves

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: DispatchWorkflow.type

What POST /repos/{owner}/{repo}/actions/workflows/{workflowfilename}/dispatches is told.

DispatchWorkflow
 .on("refs/heads/main")
 .map(_.withInput("environment", "staging").returningRunInfo)

==Inputs are ordered==

inputs is a Vector of pairs rather than a Map, so the rendered body is byte-for-byte reproducible between runs and can be asserted on directly. Forgejo does not care about the order; a test that compares request bodies does. A key set twice is sent twice, exactly as the caller built it — this type does not silently de-duplicate, because deciding which of two values wins is not a decision a client library should make.

Value parameters

inputs: the workflow_dispatch inputs the workflow file declares, in the order they will be sent
ref: the Git reference to run against. Forgejo accepts both the short form (main) and the full one (refs/heads/main); the full form is unambiguous when a branch and a tag share a name
returnRunInfo: whether to ask for a description of the run that was started. When false — the default and the API's own default — the instance answers 204 with nothing, and com.worxbend.codeberg4s.repositories.actions.RepositoryActionApi.dispatchWorkflow yields None

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

What a workflow dispatch reports back about the run it started, when it reports anything at all.

==Whether this exists is the caller's choice==

POST /repos/{owner}/{repo}/actions/workflows/{workflowfilename}/dispatches answers 204 with an empty body unless the request set return_run_info, in which case it answers 201 with this object. That is why com.worxbend.codeberg4s.repositories.actions.RepositoryActionApi.dispatchWorkflow returns an Option rather than pretending a run description is always available — and why DispatchWorkflow.returningRunInfo exists.

'''Derived from spec/swagger.v1.json's DispatchWorkflowRun definition, not from a captured response'''; see ActionArtifact for why.

Value parameters

id: the run that was started, absent when the instance did not report one
jobs: the names of the jobs the run will execute, as the workflow file spells them
runNumber: the per-repository counter of the new run — the same number as ActionRun.indexInRepo, and not an addressable identifier

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: JobAttempt.type

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: JobId.type

What POST /repos/{owner}/{repo}/actions/runners is told.

RegisterRunner.named("build-box-3").map(_.describedAs("hetzner cx42").ephemeral)

Value parameters

isEphemeral: whether the runner should de-register itself after a single job. The safer choice for a runner that executes code from pull requests, since nothing survives between jobs
name: the operator's label for the machine. Required by the spec, and explicitly '''not''' unique — registering the same name twice produces two runners, which is one reason the call is never retried

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: RegisterRunner.type

What POST /repos/{owner}/{repo}/actions/runners hands back: a new runner, and the credential it needs.

'''This value carries a credential.''' token is what the runner binary authenticates with, so this type is worth treating like a password even though it is a plain case class: its toString is safe only because RunnerRegistrationToken masks itself, which is exactly why that type is a final class and not an opaque alias.

A separate type from ActionRunner rather than a widening of it, because the payloads have almost nothing in common: the registration response is {id, uuid, token} and reports neither the runner's labels nor its status, which have not been established yet — the machine has not connected.

'''Derived from spec/swagger.v1.json's RegisterRunnerResponse definition, not from a captured response'''; see ActionArtifact for why.

Value parameters

id: the identifier the runner endpoints address the new runner by, absent when the instance did not report one
token: the one-shot registration credential. Required: a registration response without it registers nothing, so decoding fails rather than handing back a runner nobody can start
uuid: the runner's own identifier, absent when the instance did not report one

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: RunId.type

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: RunnerId.type

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: RunnerLabel.type

A one-shot credential that lets a runner register itself against a repository.

This is the value forgejo-runner register --token … consumes, and anyone holding it can attach a runner that will execute workflow code with the repository's Actions permissions. It is a credential in every sense that matters, so it carries the same redaction discipline as com.worxbend.codeberg4s.auth.ApiToken — a final class overriding toString, because an opaque alias over String cannot stop interpolation from printing it, and RunnerRegistrationToken.reveal as the single way to observe the material.

Unlike SecretValue this one travels '''from''' the instance: it is decoded out of a response body, so a decoding failure on that response would carry the raw payload — and therefore the material — into com.worxbend.codeberg4s.CodebergError.DecodingFailed, where no mask can reach it. The decoders that read the registration and registration-token responses are marked sensitive for that reason, and the pipeline reports a placeholder in place of the body excerpt on those two endpoints alone.

Instances compare structurally on the underlying material. The comparison is not constant-time.

Attributes

Companion: object
Supertypes: class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: RunnerRegistrationToken.type

Attributes

Companion: enum
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: RunnerStatus.type

Whether a registered runner is reachable, and whether it is busy.

A closed set, and one of the few Forgejo enumerates outright: the ActionRunner model in spec/swagger.v1.json declares enum: [offline, idle, active] on status. It is therefore an enum here rather than a String, so a caller filtering for available capacity cannot mistype "idle" and silently match nothing.

Attributes

Companion: object
Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: enum
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: RunnerVisibility.type

Which runners a repository's runner listing should include.

The wire spelling is a bare visible boolean, which is precisely the shape SCALA_CODE_STYLE.md says not to put in front of a caller: listRunners(owner, name, true, page) says nothing at the call site, and the parameter's meaning — true widens the listing rather than narrowing it — is the opposite of what "visible" reads like at a glance.

The parameter is always sent, rather than being left off to get the instance's default, so that a listing's contents are a property of the request and not of the Forgejo version answering it.

Attributes

Companion: object
Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: SecretName.type

The material of an Actions secret, on its way '''to''' the instance and never back.

Same redaction discipline as com.worxbend.codeberg4s.auth.ApiToken, and a final class for the same reason: an opaque type SecretValue = String has Any as its visible upper bound, so outside its defining scope value.toString and s"$value" both dispatch to String's toString and print the secret. The only way to observe the material is SecretValue.reveal, whose single legitimate caller is the request renderer that puts it in the PUT body.

'''Nothing in this library can put this value in a failure or a log.''' toString is the mask, so the generated toString of any case class holding one is too; com.worxbend.codeberg4s.CallContext carries a redacted URI and never a request body; and com.worxbend.codeberg4s.CodebergError.DecodingFailed snippets the '''response''' body, which for these endpoints is empty. The value reaches exactly one place: the bytes of the request.

'''There is no way back.''' Forgejo never returns a secret's value — see ActionSecret — so this type is write-only by construction and no decoder produces one.

Instances compare structurally on the underlying material, so a configuration value stays comparable in a test. The comparison is not constant-time; this type guards against accidental disclosure, not against a timing oracle.

Attributes

Companion: object
Supertypes: class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: SecretValue.type

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: TaskId.type

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: UpdateVariable.type

What PUT /repos/{owner}/{repo}/actions/variables/{variablename} is told.

==A rename changes what the request is==

UpdateVariableOption carries an optional name, and setting it moves the variable to a different name. That turns an otherwise idempotent PUT into one that is not: repeating it addresses a name that no longer exists. com.worxbend.codeberg4s.repositories.actions.RepositoryActionApi.updateVariable reads renamedTo to decide whether the call may be retried at all, which is why the rename lives in the command rather than in a second method.

Value parameters

renamedTo: the name to move the variable to, absent to leave it where it is. Forgejo upper-cases the new name, so the variable may end up at a spelling the caller did not write
value: the variable's new content, sent verbatim and always sent — the spec marks it required, so a PUT that meant to change only the name still has to state the value it is keeping

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: VariableName.type

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: WorkflowFileName.type

Types

The identifier of one artifact produced by a run — the {artifact_id} of /repos/{owner}/{repo}/actions/artifacts/{artifact_id}.

Attributes

Which execution of a job to read logs for — the attempt query parameter of the job-logs endpoint.

One-based, matching the attempt field of the job listing. Zero is rejected rather than being silently read as "the latest": omitting the parameter is how a caller asks for the latest attempt, and the two must not be spelled the same way.

Attributes

The instance-wide identifier of one job of a run — the {job_id} of /repos/{owner}/{repo}/actions/jobs/{job_id}.

Distinct from the job's task_id, which is the identifier of the runner task that most recently executed the job and which no endpoint in this group accepts.

Attributes

The instance-wide identifier of one Actions run — the {run_id} of /repos/{owner}/{repo}/actions/runs/{run_id}.

This is '''not''' the run's index_in_repo, the per-repository counter the web UI shows as #42 and the run listing filters on with run_number. Both are int64, both are on every run object, and the API accepts only this one in a path.

Attributes

The identifier of a registered runner, as the runner endpoints take it in a path.

'''A string, not a number, because the API says so.''' spec/swagger.v1.json declares runner_id as type: string on both GET and DELETE of /repos/{owner}/{repo}/actions/runners/{runner_id}, while the ActionRunner model carries both a numeric id and a string uuid. Rather than guess which one the route resolves — the spec does not say, and no fixture was harvested for this group — the type carries whatever the caller has and validates it as a path segment. RunnerId.of is the bridge from the numeric id every runner object reports.

Attributes

One label a runner advertises and a job's runs-on selects — ubuntu-latest, docker, self-hosted.

Only the '''filter''' side of this concept is typed. GET /repos/{owner}/{repo}/actions/runners/jobs joins its labels parameter with commas and Forgejo offers no escape for one, so a label carrying a comma would silently become two filters — exactly the hazard com.worxbend.codeberg4s.issues.LabelName guards against on the issue side. A label '''read back''' from a runner or a job stays a plain String, because dropping one this constructor dislikes would cost the caller data the instance actually holds.

Attributes

The name of an Actions secret — the {secretname} of /repos/{owner}/{repo}/actions/secrets/{secretname}.

'''A name is all a client ever learns about a secret.''' See ActionSecret for why the value is not part of this group's read model at all.

Forgejo upper-cases secret names on the way in and reports them upper-cased on the way out, so deploy_key and DEPLOY_KEY address the same secret. This type does '''not''' normalise, because doing so would make a name the caller passed differ from the name they get back for reasons this library invented; it only rejects what cannot be a path segment.

Attributes

The identifier of one runner task, as GET /repos/{owner}/{repo}/actions/tasks reports it.

No endpoint in this group takes a task id in a path — the type exists so that a task's id cannot be mistaken for a RunId or a JobId, which is exactly the confusion the three types are here to prevent.

Attributes

The name of an Actions variable — the {variablename} of /repos/{owner}/{repo}/actions/variables/{variablename}.

Unlike a SecretName this addresses something a caller can read back: a variable's value is returned by the API, because a variable is configuration and not a credential.

Attributes

The file name of a workflow, as .forgejo/workflows/ holds it — build.yml, release.yaml.

This is what Forgejo calls a workflow's id: the workflow_id of a run object and the {workflowfilename} of the dispatch endpoint are the same string, which is why one type serves both. It is the file's own name, never a path, so a / is rejected.

Attributes

In this article

Generated with