RWX Quickstart with GitLab

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

Configure the RWX GitLab Integration

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

You'll need to provide a GitLab access token with "Maintainer" privileges and the api, self_rotate, and read_repository scopes.

These permissions are necessary to read the run definitions in your .rwx directory, to trigger your runs via webhooks, and report statuses.

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

Deciding which type of token to use

Depending on the level of your GitLab subscription, you can use either a personal access token, a project access token, or a group access token.

If you use a project token, you'll need to configure a separate integration for each project. If you use a group token, it can be shared across all projects in that group. For organizations with several projects, we recommend using a group token. A personal access token may be fine for testing, but is generally not recommended for production use, unless you're using a GitLab service account.

Testing the GitLab integration

Run Definition

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

on:
  gitlab:
    push:

base:
  os: ubuntu 24.04
  tag: 1.2

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

GitLab Status Check

Take a look at the commit you just pushed in the GitLab UI. It should link to a Pipeline with the status of your RWX run. If you click into the Pipeline, it'll take you to the RWX UI where you can see the hello-world task.

Cloning Repositories

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

You can use a token in the format gitlab['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:
  gitlab:
    push:
      init:
        commit-sha: ${{ event.git.sha }}

base:
  os: ubuntu 24.04
  tag: 1.2

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

Next Steps

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