Set up a project

One person does this once for each project. After that, everyone on the project can publish a package. The steps are the same for Gradle, Maven, npm, Python, Cargo, .NET, Helm charts, Debian packages and raw files. For Docker images, see Docker and Helm.

Open your repository in the web UI, then the Publish to this repository tab.
Click Set up a project, and confirm with your second factor.

The page shows a setup line. The line works once, for 10 minutes.
Open a terminal in the project folder. Paste the line, then press Enter.
macOS or Linux
Terminal window
```
curl -fsSL https://your-server/install.sh | sh -s -- setup 'https://your-server/#/setup/trsu_...'
```
Windows
Terminal window
```
& ([scriptblock]::Create((irm https://your-server/install.ps1))) setup 'https://your-server/#/setup/trsu_...'
```
The line installs the Telesphorepo CLI and approves this computer. Then the CLI finds the project in the folder and writes telesphorepo.toml. It asks before it changes a file. It prints the repository, its format and your username, such as publishing to your-repo (maven) as YOUR_USERNAME.
The CLI asks for a CI file.

Your computer
Choose No CI file.

GitHub Actions
Choose GitHub Actions. The CLI writes .github/workflows/publish.yml.

Jenkins with a Jenkinsfile
Choose Jenkinsfile. The CLI writes Jenkinsfile.

Jenkins freestyle job
Choose Jenkins freestyle job. The CLI prints the build step. Keep it for step 10 below.
Commit the files, and push them.
Terminal window
```
git add telesphorepo.toml
git commit -m "Publish to Telesphorepo"
git push
```
Also add the CI file, if the CLI wrote one. The files hold no secrets.

Your computer: done

Done. Now publish a package.

GitHub Actions: the CI pipeline

Ask your server admin to add a CI pipeline with these values.

Where the job runs   GitHub Actions
GitHub repository    your-org/your-app
Workflow file        publish.yml
Branches             main
Repositories         your-repo

Put your GitHub repository in place of your-org/your-app.

Done when you push to main and its run shows a green check on the Actions tab of GitHub.

Jenkins: the CI pipeline

Ask your server admin to add a CI pipeline with these values.
Send this to your server admin
```
Where the job runs   Jenkins
Jenkins address      https://jenkins.example.com
Jobs                 team/app
Repositories         your-repo
```
Put your Jenkins address and the full name of your job in their places.

Set up Jenkins

Install the Jenkins plugin OpenID Connect Provider.

Manage Jenkins › Plugins › Available plugins
Open Manage Jenkins › Credentials, and add a credential.
Choose the kind OpenID Connect id token.

Fill in the ID and the Audience, then save.

ID         telesphorepo-id-token
Audience   https://your-server

Jenkins with a Jenkinsfile: the job

Make a Pipeline job that reads the Jenkinsfile from your repository.
Click Build Now on the job.

Done when the build log ends with Finished: SUCCESS.

Jenkins freestyle job: the job

Open your job, then click Configure.
Under Environment, tick Use secret text(s) or file(s).
Under Bindings, click Add, then Secret text.

Fill in the Variable and the Credentials.

Variable      OIDC_TOKEN
Credentials   telesphorepo-id-token

Under Build Steps, click Add build step, then Execute shell.

Paste the build step that the CLI printed. For Gradle, it is this:

./gradlew build
curl -fsSL https://your-server/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
telesphorepo publish

Click Save, then Build Now.

Done when the build log ends with Finished: SUCCESS.

If something goes wrong

Find your problem, then do the fix

The CLI does not find a project. Run the line in the folder that holds the project file of the repository’s format. The CLI names the files that it looks for:

Format	Project file
Maven / Gradle	`settings.gradle`, `settings.gradle.kts`, `build.gradle`, `build.gradle.kts` or `pom.xml`
npm	`package.json`
Python (PyPI)	`pyproject.toml` or `setup.py`
Cargo (Rust)	`Cargo.toml`
NuGet	a `.sln`, `.slnx`, `.csproj` or `.fsproj` file
Docker	`Chart.yaml`, for a Helm chart

A Debian or raw repository needs no project file.

The folder holds Gradle and Maven files. The CLI asks which one to use, and writes the answer as kind in telesphorepo.toml.

The setup line was used or ended. A line works once, for 10 minutes. Click Set up a project again for a new line.

The CLI says that git ignores telesphorepo.toml. CI and your teammates then do not see the file. Remove the line that the warning names from .gitignore, or run git add -f telesphorepo.toml.

The CLI cannot reach the server. Check the address. Open it in a browser.

telesphorepo is not found in a new terminal. The install puts the CLI in ~/.local/bin (on Windows, in %LOCALAPPDATA%\Programs\telesphorepo, which it adds to your user PATH). When ~/.local/bin is not on your PATH, the script asks to add it to the start-up file of your shell, such as ~/.zshrc. Answer Y, then open a new terminal. See Install the CLI.

GitHub Actions gave this job no identity token. Add id-token: write under permissions in the workflow file.

Jenkins gave this build no identity token. Check the binding: the variable is OIDC_TOKEN and the credential is telesphorepo-id-token.

The CLI refuses OIDC_TOKEN and names two addresses. The Audience of the Jenkins credential must be the address of your server, the one in telesphorepo.toml.

The server refuses the job’s token. Your server admin must set the Public base URL on Settings › General.

The token is too old. The server takes a job’s token for 10 minutes only. A freestyle job gets its token when the build starts. If the build takes longer, use a Jenkinsfile: it gets the token only for the publish stage.

No CI pipeline matches the job. Ask your server admin to check the values of the CI pipeline.

The server cannot reach Jenkins. Ask your server admin to paste the Jenkins keys into the CI pipeline. See Run the server.

The Jenkins agent runs Windows. A Jenkinsfile from the CLI runs PowerShell on a Windows agent. For a freestyle job, choose Execute Windows PowerShell and install the CLI with irm https://your-server/install.ps1 | iex.

The project is in a subfolder of the git repository. The CI job starts at the top folder. Put cd and the subfolder before telesphorepo publish. The CLI prints the line.

Permission denied on ./gradlew in CI. Run git update-index --chmod=+x gradlew, then commit and push.

Set it up by hand

The project file and the CI files

Put your server’s address in place of https://your-server, and your repository’s name in place of your-repo.

Install the CLI.

curl -fsSL https://your-server/install.sh | sh

On Windows:

irm https://your-server/install.ps1 | iex

Approve this computer. The CLI prints a link and a code. Open the link, sign in, and approve the code.

telesphorepo login https://your-server

Create telesphorepo.toml in the project folder, and commit it.

server = "https://your-server"
repo = "your-repo"

You do not change the build files. The steps for npm, Python, Cargo and .NET are on their pages: npm, Python, Rust and Cargo and .NET and NuGet. For Gradle, the project must apply the maven-publish plugin and give the project a group and a version:

plugins {
    `java-library`
    `maven-publish`
}

group = "com.example"
version = "1.0.0"

publishing {
    publications {
        create<MavenPublication>("maven") { from(components["java"]) }
    }
}

For Maven, pom.xml needs no <distributionManagement>. The CLI gives Maven the repository.

GitHub Actions

Create .github/workflows/publish.yml. This one is for Gradle and Maven. The page of each format shows its own setup step in place of actions/setup-java.

on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: 21
      - run: curl -fsSL https://your-server/install.sh | sh
      - run: telesphorepo publish

Jenkinsfile

Create Jenkinsfile. This one is for Gradle. For Maven, the build line is mvn -B verify. The Publish to this repository tab shows the file for the tool of your repository.

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        script {
          if (isUnix()) {
            sh './gradlew build'
          } else {
            powershell '.\\gradlew.bat build'
          }
        }
      }
    }
    stage('Publish to your-repo') {
      steps {
        // The token is good for 10 minutes, so only this stage gets it.
        withCredentials([string(credentialsId: 'telesphorepo-id-token', variable: 'OIDC_TOKEN')]) {
          script {
            if (isUnix()) {
              sh '''
                curl -fsSL https://your-server/install.sh | sh
                export PATH="$HOME/.local/bin:$PATH"
                telesphorepo publish
              '''
            } else {
              powershell '''
                & ([scriptblock]::Create((irm https://your-server/install.ps1)))
                telesphorepo publish
              '''
            }
          }
        }
      }
    }
  }
}

Jenkins freestyle job

A freestyle job needs no file. Choose Jenkins freestyle job at the top of the page to see its steps.

Set up a project

macOS or Linux

Windows

Your computer

GitHub Actions

Jenkins with a Jenkinsfile

Jenkins freestyle job

Your computer: done

GitHub Actions: the CI pipeline

Jenkins: the CI pipeline

Set up Jenkins

Jenkins with a Jenkinsfile: the job

Jenkins freestyle job: the job

If something goes wrong

Set it up by hand

GitHub Actions

Jenkinsfile

Jenkins freestyle job