Installing an App

Owned by PIPEFORCE
Last updated: Jul 28, 2024
2 min read

From GitHub​

You can install any PIPEFORCE app directly from any GitHub repository.

Make sure the repository you would like to deploy from has a folder structure like this:

  • properties/

    • global/

      • app/

        • tld.domain.myapp/

          • The contents of your app start in this level.

Make sure you install only from trusted sources since installing apps from untrusted sources could harm your system!

Public repo​

Let's assume you have a public GitHub repository with a name like acme/my-pipeforce-app, then you can use the app.install command to install from this repository like this example shows using a pipeline:

pipeline: - app.install: github: "acme/my-pipeforce-app"

Or you can use the CLI:

pi command app.install github=acme/my-pipeforce-app

Since GitHub allows only a few requests for non-authenticated API calls and limits the transfer bytes, you can install only very small apps using this public repo approach. If you have to install apps with many resources, use the private repo approach since this has higher limits for API calls and bytes transferred.

Private repo​

In case you would like to install from a private repo, you have to do these additional steps to register the GitHub access token as secret:

Create a GitHub personal access token​

At first you need to create a personal access token in GitHub which allows to read your repo. See GitHub Docs how to do so.

Register access token as credentials​

Copy the GitHub access token. Open the PIPEFORCE portal and then go to LOW CODE -> Secrets. Create a new secret of type header with a name of your choice, for example my-github-token, and as value, use this format:

Authorization: token COPY_YOUR_TOKEN_HERE

Save your new secret.

Refer to the secret in the command​

Then, you can use it in the app.install command like this:

Via GitHub Action

DRAFT: NEEDS REVIEW + TEST

In order to setup a CI/CD process, you can use GitHub Actions. Using this approach, you can automate the deployment of an app to a PIPEFORCE instance every time a specific event happened in the repository. Such an event for example could be a push to a specific branch. Every time a new push to this branch is executed, the app will be updated on the instance as configured before.

To enable this approach, you have to follow the steps below to create a GitHub Action configuration and enable it.

Go to your local repo folder of your app, create a new file at root level: .github/workflows and add these lines to the file:

Adjust the file to fit your needs:

  • Define the trigger when the action should run. See GitHub Actions documentation about all options.

  • Change the env variables accordingly:

    • PI_INSTANCE_URL = The url of the instance you would like to deploy to.

    • PI_SECRET_NAME = The name of the GitHub personal token stored inside PIPEFORCE under this name as described for Private Repo.

    • PI_USERNAME_PASSWORD = The username and password of the user who is allowed to execute the app.install command on PIPEFORCE. Make sure it is stored in GitHub as secret under this name and in format username:password.

    • GH_REPO = The name of the repo which contains the apps to be deployed.

    • GH_BRANCH = The branch of the repo to be deployed.

Finally push your changes to GitHub.

In future, every time the trigger as defined in on: section happens, the app gets updated.

From Marketplace

In order to install an app from the Apps Marketplace, see here: