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
• 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 subtypes are

• Comment: Track comments
• Label: Track issue labels
• PullRequest: Track and open pull requests
• 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. Subtypes with fine-grained resource parameters are for pipeline instancing.

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 (required)	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.

Contributing

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

prek install

Using this hook is optional but the code must pass nix fmt, cargo fmt, 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