Cookbook — gitea4s

Usage cookbook

Representative calls by namespace. The published surface is broader — see the changelog for the full list.

Repositories and Git data

client.repos.get(owner, repo)
client.repos.branches(owner, repo).runCollect
client.repos.tags(owner, repo).runCollect
client.repos.commit(owner, repo, sha)
client.repos.gitTree(owner, repo, sha)
client.repos.contents(owner, repo, filepath = "docs/readme.md", ContentsParams(ref = Some("main")))
client.repos.rawFile(owner, repo, filepath = "README.md", ContentsParams.default) // Chunk[Byte]
client.repos.archive(owner, repo, archive = "main.zip")                            // Chunk[Byte]
client.repos.languages(owner, repo)
client.repos.collaborators(owner, repo).runCollect

Issues

client.issues.create(owner, repo, CreateIssue(title = "Bug report", body = Some("...")))
client.issues.edit(owner, repo, index = 12, EditIssue(title = Some("Updated")))
client.issues.close(owner, repo, index = 12)
client.issues.comment(owner, repo, index = 12, body = "Confirmed")
client.issues.addLabels(owner, repo, index = 12, labels = Chunk(1L, 2L))
client.issues.list(owner, repo).runCollect

Pull requests

client.pulls.list(owner, repo).runCollect
client.pulls.create(owner, repo,
  CreatePullRequestOption(base = Some("main"), head = Some("feature"), title = Some("...")))
client.pulls.createReview(owner, repo, index = 7,
  CreatePullReviewOptions(body = Some("LGTM"), event = Some(PullReviewState.Approved)))
client.pulls.merge(owner, repo, index = 7,
  MergePullRequestOption(mergeMethod = MergePullRequestMethod.Squash))
client.pulls.diffOrPatch(owner, repo, index = 7, PullRequestDiffType.Diff)

Releases and commit statuses

client.releases.list(owner, repo).runCollect
client.releases.latest(owner, repo)
client.releases.byTag(owner, repo, tag = "v1.0.0")
client.repos.createStatus(owner, repo, sha,
  CreateStatusOption(state = Some(CommitStatusState.Success), context = Some("ci/build")))
client.repos.combinedStatusByRef(owner, repo, ref = "main")

Notifications

client.notifications.unreadCount
client.notifications.list().take(20).runCollect

Runnable examples

The repository ships eight runnable examples. Without credentials they print the target API version and make no network calls, which is how CI runs them.

./mill examples.run    # hermetic when no credentials are present

GITEA_URL=https://gitea.example GITEA_TOKEN=... \
  ./mill examples.runMain io.worxbend.gitea4s.examples.ListMyRepos

Example	Shows	Extra environment
`ShowApiReference`	the current user	—
`ListMyRepos`	streaming a user's repositories	—
`ListNotifications`	unread count and threads	—
`ListReleases`	repository releases	`GITEA_OWNER`, `GITEA_REPO`
`ListPullRequests`	pull requests with params	`GITEA_OWNER`, `GITEA_REPO`
`ListBranchesAndTags`	two streams in one program	`GITEA_OWNER`, `GITEA_REPO`
`OrgMembers`	organization members	`GITEA_ORG`
`SearchUsers`	user search	`GITEA_USER_QUERY`

Building from source

./mill __.compile            # compile all modules
./mill __.test               # hermetic unit tests
./mill examples.run          # hermetic by default
./mill compatibility.check   # public-API binary-compat guard

Live integration tests are opt-in and require GITEA_IT to be set in addition to a server and credentials — without it every live test is reported as ignored and no network call is made. See CONTRIBUTING for the full probe matrix and the API design conventions the client follows.