Skip to main content
Ryvn integrates with GitHub Actions to automate your build and deployment workflow. This integration enables automatic releases when you push changes to your repository, making it easier to maintain a consistent deployment process.

​
Prerequisites

Before setting up GitHub Actions integration, ensure you have:
  • A service created in Ryvn from a GitHub repository
  • Admin access to the GitHub repository
  • A deployed installation of your service

​
Supported service types

GitHub Actions integration is available for the following service types:
  • Server: For HTTP/HTTPS services
  • Terraform: For infrastructure as code services
  • Helm Chart: For Helm Chart services

​
Setting up GitHub Actions

1

Access GitHub Actions setup

There are two ways to set up GitHub Actions:
  1. After creating a new service, click the Setup GitHub Actions button in the success screen
  2. For existing services, click the three-dot menu next to your service and select Setup GitHub Actions
2

Configure workflow

In the setup dialog:
  1. Review the workflow description
  2. Click Setup GitHub Actions to proceed
  3. Wait while Ryvn creates the necessary workflow files
3

Review pull request

Once the setup is complete:
  1. Click View Pull Request to open the created PR in GitHub
  2. Review the workflow configuration
  3. Merge the pull request to enable automated releases

​
Understanding the workflow

The GitHub Actions workflow Ryvn creates will:
  1. Build your application when you push changes
  2. Create a release in Ryvn
  3. Deploy the release to environments based on your release channel configuration

​
Workflow files

Ryvn creates two main files in your repository:
  • .github/workflows/ryvn.yml: The main workflow configuration
  • .github/ryvn.yml: Configuration for release creation

​
Release process

When you push changes to your repository:
  1. GitHub Actions builds your application
  2. If successful, it creates a release in Ryvn
  3. The release is automatically deployed to environments subscribed to the appropriate release channel

​
Version control

Ryvn follows semantic versioning (MAJOR.MINOR.PATCH) for releases. You can control version numbers by:
  • Using Git tags (e.g., v1.2.3)
  • Letting Ryvn auto-increment the version

​
Troubleshooting

Common issues and solutions:

​
Workflow not running

  • Verify the workflow file exists in .github/workflows/ryvn.yml
  • Check GitHub repository permissions
  • Ensure the branch is properly configured

​
Build failures

  • Review build logs in GitHub Actions
  • Verify all dependencies are properly specified
  • Check resource limits in workflow configuration

​
Deployment issues

  • Confirm release channel configuration
  • Check maintenance window settings
  • Review environment health checks

​
ryvn get returns an empty list or 403 only in CI

The job is running as the repository’s CI identity, not as the service user in RYVN_CLIENT_ID. See Which identity a job uses.
If you need to recreate the GitHub Actions workflow, you can use the Setup GitHub Actions option again, which will create a new pull request with the latest configuration.

​
Authentication

Workflows authenticate to Ryvn with the job’s own GitHub identity. GitHub Actions issues every job a short-lived OIDC token; the Ryvn CLI exchanges it for a short-lived Ryvn credential the first time a step calls it (currently valid for up to twelve hours; Ryvn is reducing this to one hour in a staged rollout) scoped to publishing releases for the services this repository owns. Nothing is stored in your repository, and there is nothing to rotate. The only requirement is that the job can request its token:
Workflows generated by Ryvn already include it. A hand-written workflow with id-token: write and a current Ryvn CLI works the same way; no registration or environment variable is needed.

​
What the credential can do

The credential is bound to the ci-release-publisher role for each service whose source is this repository: it can read those services and create releases for them, including pushing built images to a private registry bound to the service (registry publish permission is granted per bound registry automatically). It cannot read secrets, change environments, or touch services in other repositories. A job that needs more (for example ryvn promote) fails with a 403 that names the identity and the missing permission; an organization admin can grant the extra role to the repository’s CI identity from the GitHub integration page or with the CLI, and the next run picks it up. Ryvn creates one CI identity per connected repository automatically. You can see it, and its grants, on the integration page and in ryvn integrations github repos.

​
Which identity a job uses

When a job has id-token: write, the CLI uses the repository’s CI identity and does not use RYVN_CLIENT_ID / RYVN_CLIENT_SECRET, even if both are set. (A valid RYVN_ACCESS_TOKEN in the environment takes precedence over both.) The secrets are only consulted if the exchange is refused because your organization is not enabled for keyless authentication, the exchange is rate limited, or the repository is trusted by several organizations and RYVN_ORG_ID is unset; in each case the CLI prints a warning before falling back. This matters when a workflow does more than publish releases. The CI identity’s ci-release-publisher role covers the services this repository owns and nothing else, so the same command can behave differently in CI than on a laptop with the same secrets:
  • List commands such as ryvn get environment return only what the identity can read, which may be an empty list with exit code 0, not an error.
  • Single-resource reads and writes the identity lacks permission for fail with a 403.
To see which identity a run is using, add ryvn auth status to the workflow. In a job with id-token: write it reports auth type github-oidc; if the CLI fell back to the static secrets, the fallback warning appears on stderr and the reported user is the service user. You have two options when a workflow needs permissions beyond release publishing:
  1. Grant the CI identity more roles. In the Ryvn console go to Settings → Connections → GitHub and assign additional roles (for example viewer) to the repository’s CI identity. Roles are per repository, not per workflow, so every job in that repository with id-token: write gets them.
  2. Use a service user for that job. Remove id-token: write from the job’s permissions block and set RYVN_CLIENT_ID / RYVN_CLIENT_SECRET (and RYVN_ORG_ID). Without the token permission the CLI cannot obtain a GitHub identity and authenticates as the service user, with exactly that user’s roles. Use this when one workflow should have narrower or different permissions than the rest of the repository.

​
Environment variables you may need

​
Static credentials

Repositories connected before keyless authentication was enabled have RYVN_CLIENT_ID and RYVN_CLIENT_SECRET repository secrets. They keep working during the transition: a current CLI tries the GitHub identity first and only uses the secrets if your organization has not been enabled for keyless authentication yet (see Which identity a job uses). Once your organization is enabled and a run has succeeded without them, you can delete both secrets from the repository; the workflow file may still reference secrets.RYVN_CLIENT_ID, which is harmless (GitHub passes an empty value). When Ryvn retires static credentials for your organization it removes the secrets itself, and Setup GitHub Actions generates workflows without the secret block. If the workflow’s CLI version predates keyless authentication it prints a notice and continues with the secrets. Upgrade the install-ryvn-cli step (or pin a newer version) to switch over.

​
Token lifetime, replay and revocation

  • Each exchanged credential is short-lived: up to twelve hours today, one hour once Ryvn’s staged lifetime reduction completes. The CLI re-exchanges automatically if a job outlives it.
  • A GitHub OIDC token can be exchanged once. Presenting the same token again is rejected, so a leaked token from a finished job is useless.
  • Removing the repository from the GitHub App installation, or disconnecting it in Ryvn, deletes its CI identity and every grant. Removing a service’s repository pointer removes that service’s grant on the next reconcile. Credentials already issued expire on their own at the end of their lifetime (see above).
Never commit Ryvn credentials or sensitive information directly in workflow files. With keyless authentication there is nothing to commit; if you still use static credentials, keep them in GitHub Secrets.