RWX Quickstart with Forgejo

If you're not already familiar with RWX, you may want to start with the general getting started guide.

Codeberg is powered by Forgejo, so this guide also applies to Codeberg repositories.

Configure the RWX Forgejo Integration

Visit your RWX organization's VCS integrations page and click "Configure a Forgejo integration".

You'll need to provide:

  • A description for the integration.
  • The hostname of your Forgejo instance. For Codeberg, use codeberg.org.
  • The Forgejo organization whose repositories RWX should manage.
  • A service account access token with read:user, write:organization, and write:repository scopes.

These permissions are necessary to read the run definitions in your .rwx directory, create the organization webhook that triggers runs, create read-only deploy keys for cloning connected repositories, and report statuses back to Forgejo.

Once you create the integration, you'll be redirected to a page where you'll select the repositories that you want to connect.

Testing the Forgejo integration

Run Definition

To test the Forgejo integration, create a file named .rwx/push.yml, commit, and push it to your repository.

on:
  forgejo:
    push:

base:
  image: ubuntu:24.04
  config: rwx/base 1.0.2

tasks:
  - key: hello-world
    run: echo hello world

Forgejo Status Check

Take a look at the commit you just pushed in the Forgejo UI. It should show a commit status for the RWX run. Click the status to open the RWX UI and see the hello-world task.

Cloning Repositories

Installing the Forgejo integration also provides a way to clone your repositories.

You can use a token in the format forgejo['YOUR_ORG/YOUR_REPO'].ssh-key with the git/clone package to clone your repository.

To test cloning, update .rwx/push.yml to contain the following, and then commit and push:

on:
  forgejo:
    push:
      init:
        commit-sha: ${{ event.git.sha }}

base:
  image: ubuntu:24.04
  config: rwx/base 1.0.2

tasks:
  - key: code
    call: git/clone 2.0.7
    with:
      repository: [email protected]:YOUR_ORG/YOUR_REPO.git
      ref: ${{ init.commit-sha }}
      ssh-key: ${{ forgejo['YOUR_ORG/YOUR_REPO'].ssh-key }}

Replace forgejo.example.com with the host for your Forgejo instance.

Next Steps

For continuing to build a graph of tasks on top of your code task, see the CI reference workflow guide.