From afb7cfb2a937795e53d87a7c7f7993722308f773 Mon Sep 17 00:00:00 2001 From: Benedikt Reiser Date: Thu, 19 Nov 2026 23:14:36 +0100 Subject: [PATCH 1/2] docs(readme): use application access tokens in CI/CD pipelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document Portal's application access tokens (`ipat_…`) as the credential for pipelines and integrations: what each permission allows and which command needs it, where to create and revoke a token, that it acts in its own organization, and the 401/403 answers. Add examples for uploading and publishing from a pipeline (with a GitHub Actions step) and for downloading a build. Co-Authored-By: Claude Opus 5.5 --- readme.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 2f04d7f..a738c11 100644 --- a/readme.md +++ b/readme.md @@ -99,7 +99,7 @@ innoactive-portal auth status innoactive-portal auth logout ``` -Alternatively, you can provide credentials as environment variables. You can use either a Bearer token issued by Portal or a user's username (email address) and password combination. These always take precedence over a token stored via `auth login`. +Alternatively, you can provide credentials as environment variables. You can use either a Bearer token issued by Portal, such as an [application access token](#application-access-tokens-for-cicd-pipelines-and-integrations), or a user's username (email address) and password combination. These always take precedence over a token stored via `auth login`. To use a bearer token, set: @@ -114,6 +114,46 @@ export PORTAL_BACKEND_USERNAME=jane.doe@example.org export PORTAL_BACKEND_PASSWORD=supersecure-password ``` +Portal refuses passwords for accounts that use or require two-factor authentication. Use an +application access token for pipelines instead. + +### Application access tokens for CI/CD pipelines and integrations + +A CI/CD pipeline or another machine that works with one application should use an +**application access token**, not a person's credentials. A token belongs to one application +in one organization, not to the person who created it. It can only do what its permissions +allow: + +| Permission | Allows | Command | +| --- | --- | --- | +| Upload builds | uploading new builds of the application | `applications v2 upload-build` | +| Publish builds | pointing the application's launch configurations at a build | `applications v2 update-launch-configuration` | +| Download builds | downloading the application's build archives | `applications v2 builds download` | + +Every token can also read its application (`applications v2 get `), the +application's builds (`applications v2 builds get `) and its launch configurations. +It can't do anything else: it can't list applications, edit, delete or share anything, or +reach another application. + +To create a token, open the application in Portal and go to **Access Control** → +**Access Tokens** → **Create access token**. Choose a name, the permissions and an expiry. +Upload and publish tokens can only be created in the organization that owns the application. +An organization the application is shared with can create download tokens. Portal shows the +token (`ipat_…`) only once, so store it in your pipeline's secret store straight away. You can +revoke tokens on the same page. To rotate a token, create a new one, switch your pipeline over +to it, then revoke the old one. + +The CLI sends the token like any other bearer token: + +```sh +export PORTAL_BACKEND_ACCESS_TOKEN=ipat_... +``` + +You don't need to name an organization: the token acts in the organization it was created +in, and a request that names another organization (`Portal-Organization-Id`) is refused. +Portal answers `401 Unauthorized` for an expired or revoked token, and `403 Forbidden` for a +command the token has no permission for. + ## Configuration Apart from the authentication credentials, you can also opt to run the client against another Portal instance than the default, which is `https://api.innoactive.io`. @@ -150,6 +190,68 @@ innoactive-portal applications v2 upload-build \ You can run `innoactive-portal applications v2 upload-build --help` to get more information on available parameters. +### Uploading and publishing from a CI/CD pipeline + +With an [application access token](#application-access-tokens-for-cicd-pipelines-and-integrations) +in `PORTAL_BACKEND_ACCESS_TOKEN`, a pipeline uploads a build and then makes it live: + +```sh +# Needs "Upload builds". Prints the new build as JSON, including its id. +innoactive-portal applications v2 upload-build ./build.zip \ + --application-id "$APPLICATION_ID" \ + --version "$VERSION" \ + --xr-platform win-non-vr \ + --executable-path MyApp.exe + +# Needs "Publish builds". Points the application's win-non-vr launch configuration at the build. +innoactive-portal applications v2 update-launch-configuration "$APPLICATION_ID" win-non-vr "$BUILD_ID" +``` + +What the upload does depends on the token's permissions: + +- **Upload builds only:** Portal stores the build but doesn't put it into use. The build can + only name XR platforms the application already has launch configurations for. +- **Upload builds and Publish builds:** the build goes live the same way as an upload by a + person. Launch configurations that don't have a build yet get it right away. The others + switch to it once Portal has scanned and validated it. + +`update-launch-configuration` switches a launch configuration straight away, even before +Portal has validated the build. Use `applications v2 builds get ` to check a +build's processing and validation state first. + +A GitHub Actions step with the token stored as the repository secret `PORTAL_ACCESS_TOKEN` +(GitHub's default shell runs with `-e -o pipefail`, so a failed upload fails the step): + +```yaml +- uses: actions/setup-python@v7 + with: + python-version: "3.12" +- name: Upload and publish the build on Portal + env: + PORTAL_BACKEND_ACCESS_TOKEN: ${{ secrets.PORTAL_ACCESS_TOKEN }} + APPLICATION_ID: 8feaa9c8-5aaf-4d49-8eef-0c20e8c73d9c + VERSION: 1.0.2 + run: | + pip install portal-client@git+https://github.com/Innoactive/Portal-Python-CLI.git@main + BUILD_ID=$(innoactive-portal applications v2 upload-build ./build.zip \ + --application-id "$APPLICATION_ID" --version "$VERSION" \ + --xr-platform win-non-vr --executable-path MyApp.exe | jq -r .id) + innoactive-portal applications v2 update-launch-configuration "$APPLICATION_ID" win-non-vr "$BUILD_ID" +``` + +### Downloading a build + +With the "Download builds" permission (or as a user who may download the application): + +```sh +innoactive-portal applications v2 builds download --filepath ./build.apk +``` + +If you leave out `--filepath`, the CLI saves the archive in a temporary directory. Either way, +it prints the path of the file. Other tools can download the build's `application_archive` +URL (see `applications v2 builds get `) by sending the header +`Authorization: Bearer `. + ### Managing virtual machines Virtual machines live in session management, set `PORTAL_SESSION_MANAGEMENT_ENDPOINT` for From 05b6681282d30a6f9436618fbaa0c424cbce0f88 Mon Sep 17 00:00:00 2001 From: Benedikt Reiser Date: Thu, 19 Nov 2026 23:14:50 +0100 Subject: [PATCH 2/2] docs(readme): make the upload example copy-pasteable The comments after each line continuation broke the command when pasted into a shell. The command now runs as is, and the options are explained below it. Co-Authored-By: Claude Opus 5.5 --- readme.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/readme.md b/readme.md index a738c11..4c0403d 100644 --- a/readme.md +++ b/readme.md @@ -179,15 +179,21 @@ export PORTAL_SESSION_MANAGEMENT_ENDPOINT=https://my-session-mgmt.example.org You will need the application's identity from Portal as well as the application archive (.zip or .apk) to be uploaded. ```sh -innoactive-portal applications v2 upload-build \ -./my-new-app-version.zip \ # application archive to be uploaded ---application-id 8feaa9c8-5aaf-4d49-8eef-0c20e8c73d9c \ # the id of the application this version belongs to ---version 1.0.2 \ # version number of the new version ---xr-platform win-non-vr \ # the XR platform this version is for, can be specified multiple times for multiple platforms ---launch-args='--my-custom-arg' \ # custom launch arguments for the application ---changelog='This version contains some bugfixes and new features' # changelog for the new version +innoactive-portal applications v2 upload-build ./my-new-app-version.zip \ + --application-id 8feaa9c8-5aaf-4d49-8eef-0c20e8c73d9c \ + --version 1.0.2 \ + --xr-platform win-non-vr \ + --launch-args='--my-custom-arg' \ + --changelog='This version contains some bugfixes and new features' ``` +- `./my-new-app-version.zip`: the application archive to upload +- `--application-id`: the ID of the application the build belongs to +- `--version`: the build's version number +- `--xr-platform`: the XR platform the build is for; repeat it for several platforms +- `--launch-args`: custom launch arguments for the application +- `--changelog`: the build's changelog + You can run `innoactive-portal applications v2 upload-build --help` to get more information on available parameters. ### Uploading and publishing from a CI/CD pipeline