Start tasks from CI

A CI job or your own integration needs a token that keeps working. Leave out expiresInSeconds for a token without an expiry. When you create one, devboxes warns that the token works until you revoke it. Delegations describes token lifetimes. Delegation tokens have fine-grained permissions, so grant a CI token only the operations it needs. A token needs the operations of the Blueprint that it starts: publication.commit for a Blueprint that publishes, and the operations of its capabilities.

Your own integration can run operations with the CLI, or call the HTTP API with the token.

This prompt sets up a GitHub Actions workflow that starts a devboxes task once a week:

To set it up yourself:

1. Create a delegation without expiresInSeconds that allows sessions.dispatch and the operations of the Blueprint that the job starts. For a Blueprint that publishes, this is publication.commit:

   {
     "organizationId": "<organization id>",
     "name": "GitHub Actions",
     "operations": ["sessions.dispatch", "publication.commit"]
   }

   devboxes invoke delegations.create --input @ci-delegation.json

2. Save the token from the result as a secret in your CI, named DEVBOXES_TOKEN.

3. In the job, install the CLI as shown in Install the CLI. Set DEVBOXES_TOKEN from the secret, and start a task with devboxes invoke sessions.dispatch.

4. When you no longer need the token, revoke it with delegations.revoke.

Create the token in the dashboard

A token made in the devboxes dashboard can start Blueprints that don't publish. The dashboard can't grant publication.commit, so a job that starts a Blueprint that publishes needs a token from step 1. For a Blueprint that doesn't publish, you can create the token in the dashboard in place of step 1:

1. Open Settings > Tokens and choose Create a token.
2. Under What is this token for?, choose A CI job or a script.
3. On Review your token, check the token's access under Access. The token needs the operations of the Blueprint's capabilities, such as repositories.github-write. To add them, choose Change access. Choose when the token Expires, for example Never, then choose Create token.
4. Copy the token from Copy your token. devboxes shows it only once. Continue at step 2.

To revoke the token, choose Revoke next to its name under Settings > Tokens.