Table of Contents

• Concourse Forgejo Resource
• Installation
• On worker
• On pipeline
• Resource
• Usage
• Status
• Get step
• Put step
• Comment
• Get step
• Put step
• Label
• Get step
• Put step
• Release
• Get step
• Put step
• Pull Request
• Get step
• Put step
• Debian
• Get step
• Put step
• Contributing

Concourse Forgejo Resource

A Forgejo Resource for Concourse CI using Forgejo API.

Installation

On worker

Follow these instructions to install the forgejo resource on a worker. The provided image output of flake.nix builds a container image with the 3 executables /opt/resource/{check,in,out}:

nix build .#image
./result | docker load

Upload the rootfs.tgz of this image to a worker and place it along with resource_metadata.json in the resource types directory:

resource_types
└ forgejo
  ├ rootfs.tgz
  └ resource_metadata.json

On pipeline

If this resource is not installed on a worker, use the provided container image:

- name: forgejo
  type: registry-image
  source:
    repository: codeberg.org/aniva/concourse-forgejo

Resource

To use this resource type, declare a resource:

resources:
- name: forgejo-custom
  type: forgejo
  icon: list-status
  source:
    auth_token: ((git.auth_token))
    url: ((git.url))
    type: ...
	...

The authentication token has to come from a bot user. Generate this token of either via the UI or via an admin command:

forgejo admin user generate-access-token \
	--username $USERNAME \
	--token-name $TOKEN_NAME \
	--scopes write:repository,write:issue,write:notification,write:misc \
	--config $CONFIG_PATH

The source.type field specifies the type of this resource within forgejo. The available resource types are

• Comment: Track comments
• Debian: Track and publish Debian packages
• Label: Track issue labels
• PullRequest: Track and open pull requests; Can be used for instanced pipelines
• Release: Track and publish releases
• Status: Track and set statuses of commits

Depending on the type field, there may have to be additional fields in the source configuration.

Usage

Status

Tracks commit statuses. A version is a revision combined with a list of status ids.

resources:
- name: build-status
  type: forgejo
  source:
    type: Status
    auth_token: ((forgejo.auth_token))
    url: https://my-forgejo-instance.net
    owner: my-org
    repo: my-repo

Field	Description
auth_token (required)	Personal access token with read:repository scope
url (required)	Base URL of the Forgejo instance
owner (required)	Owner of the repository (user or organization)
repo (required)	Name of the repository
branch	Branch for tracking statuses
pattern	Filter statuses by an optional regex

Get step

Retrieves statuses as a list of CommitStatus to status.json.

Put step

Sets a status

- put: build-status
  params:
	state: <state of status>
	rev: <revision of commit>
    context: <optional context, default to pipeline job name>
    description: <optional description>
    target_url: <optional target url, default to CI path>

Comment

Track comments. A version is a comment id, which increments when there is a new comment or an existing comment is modified

resources:
- name: issue-comment
  type: forgejo
  source:
    type: Comment
    auth_token: ((forgejo.auth_token))
    url: https://git.example.com
    owner: my-org
    repo: my-repo

Field	Description
auth_token (required)	Personal access token with read:repository scope
url (required)	Base URL of the Forgejo instance
owner (required)	Owner of the repository
repo (required)	Name of the repository
issue	Issue or branch id; Reads from the entire repository if not provided
pattern_user	Filter comment users by an optional regex
pattern_body	Filter comment bodies by an optional regex

Get step

Retrieves a comment as Comment object to comment.json.

Put step

Posts a comment

- put: issue-comment
  params:
    index: <optional issue index>
	body: <comment text>

Label

Tracks issue/PR labels. A version is an ordered list of label id's.

resources:
- name: labels
  type: forgejo
  source:
    type: Label
    auth_token: ((forgejo.auth_token))
    url: https://my-forgejo-instance.net
    owner: my-org
    repo: my-repo

Field	Description
auth_token (required)	Personal access token with read:repository scope
url (required)	Base URL of the Forgejo instance
owner (required)	Owner of the repository (user or organization)
repo (required)	Name of the repository
issue	Issue or Branch id

Get step

Retrieves labels to names.json.

Put step

Adds and deletes a number of labels, referenced by name, to an issue or PR.

- put: labels
  params:
    add: ['category/feature']
    remove: ['progress/need_review']

Release

Tracks Forgejo releases. The version is the tag name of a release (for example, v1.2.3).

resources:
- name: my-repo-release
  type: forgejo
  source:
    type: Release
    auth_token: ((forgejo.auth_token))
    url: https://my-forgejo-instance.net
    owner: my-org
    repo: my-repo

Field	Description
auth_token (required)	Personal access token with read:repository scope
url (required)	Base URL of the Forgejo instance
owner (required)	Owner of the repository (user or organization)
repo (required)	Name of the repository
pre_release	Set to true to include pre-releases. Defaults to false
draft	Set to true to include draft releases. Defaults to false
tag_filter	Regular expression. Only releases whose tag name matches are considered

Get step

Downloads the release. The following files are written:

• tag: tag name of the release (for example, v1.2.3),
• name: release title,
• body: release description in Markdown,
• release.json: The full release object returned by the Forgejo API,
• all attachments, using their original file names.

Put step

Creates a new release. Requires write:repository scope on the token.

- put: my-repo-release
  params:
    tag: path/to/tag
    name: path/to/name
    body: path/to/body
    git_rev: path/to/git_rev
    draft: false
    pre_release: false
    attachments:
      - dist/
      - checksums.txt

Parameter	Default	Description
tag	release/tag	Path to a file containing the tag to create the release on. If the tag does not exist, a new tag is created. Required: the step fails if the file is absent and no path is given.
name	release/name	Path to a file containing the release title.
body	release/body	Path to a file containing the release description in Markdown.
git_rev	release/git_rev	Path to a file containing the branch name or commit SHA to tag. Used when creating new tags. Falls back to the tip of the default branch if the file is absent.
draft	false	Publish as a draft.
pre_release	false	Mark as a pre-release.
attachments	[]	List of paths to upload as release attachments. Can include directory paths, which will be walked recursively, including all contained files. Symbolic links are not followed.

Pull Request

Tracks pull requests. A version is a list of pull request id's representing the set of pull requests currently fitting into the filtering criterion.

resources:
- name: repo-pull-request
  type: forgejo
  source:
    type: PullRequest
    auth_token: ((forgejo.auth_token))
    url: https://my-forgejo-instance.net
    repo: my-repo
    state: open|closed|all
	poster: optional poster name

Field	Description
auth_token (required)	Personal access token with read:repository scope
url (required)	Base URL of the Forgejo instance
owner (required)	Owner of the repository (user or organization)
repo (required)	Name of the repository
state	State of a pull request, defaults to open
poster	Poster user id

Get step

Retrieves a list of Pull Request Info (id, title, url) to info.json.

Put step

Not implemented.

Debian

Tracks Forgejo Debian package registry entries. A version is a {name, version} pair identifying a specific package version.

resources:
- name: my-deb
  type: forgejo
  source:
    type: Debian
    auth_token: ((forgejo.auth_token))
    url: https://my-forgejo-instance.net
    owner: my-org
    distribution: bookworm
    component: main

Field	Description
auth_token (required)	Personal access token with read:package and write:package scopes
url (required)	Base URL of the Forgejo instance
owner (required)	Owner of the package (user or organization)
distribution (required)	Debian distribution (e.g. bookworm, focal)
component	Debian component (default: main)
package_name	Filter check to a specific package name (exact match)
architecture	Filter in downloads to a specific architecture (e.g. amd64). Architecture-independent packages (all) are always included

Get step

Downloads the .deb file(s) for the package version. The following files are written:

• package.json: The full package object returned by the Forgejo API
• files.json: The list of package files with checksums
• All .deb files, using their original file names

If architecture is set in the source, only files matching that architecture (plus architecture-independent all packages) are downloaded.

Put step

Uploads .deb file(s) to the registry. Requires write:package scope on the token.

When the version is determined at build time and cannot be baked into the pipeline config, use archive_file — a path to a file containing the .deb filename. The .deb file is expected to be in the same directory as the archive file:

- put: my-deb
  params:
    archive_file: deb/filename

If deb/filename contains myapp_1.0.0_amd64.deb, the resource uploads deb/myapp_1.0.0_amd64.deb.

Alternatively, use files to specify .deb paths directly:

- put: my-deb
  params:
    files:
      - build/myapp_1.0.0_amd64.deb

Parameter	Default	Description
archive_file		Path to a file containing the .deb filename, relative to the build's source directory. The .deb file is expected in the same directory. Takes priority over files.
files	[]	List of paths to .deb files to upload, relative to the build's source directory. Filenames must follow the Debian naming convention name_version_arch.deb. Ignored when archive_file is set.
distribution	source distribution	Override the Debian distribution for this upload.
component	source component	Override the Debian component for this upload.

If a package with the same name, version, distribution, component, and architecture already exists, the upload will fail with a 409 Conflict error. Delete the existing package version first to re-publish.

Contributing

Use the provided flake development shell, and install pre-commit hook:

prek install

Using this hook is optional but the code must pass both cargo check and cargo clippy --tests.

This crate builds the 3 executables required in a concourse resource type:

cargo run --bin check|in|out

The target .#image builds an image where the 3 resource executables are in /opt/resource.

To manually run a resource, create a JSON object with the requisite fields and run it with check, in, out:

{
	"source": {
		"auth_token": "<auth-token>",
		"url": "<forge-url>",
		"owner": "<user>",
		"repo": "<repo>",
		"type": "Status"
	},
	"params": {
	    ...
	}
}

cargo run --bin check < example-check.json
cargo run --bin in /tmp/ < example-in.json
cargo run --bin out /tmp/ < example-out.json