Working with bitrise.yml via the Bitrise CLI
The bitrise yml commands work with bitrise.yml files:
- Download and upload the CI configuration of a project on Bitrise.
- Validate a file before you use it.
- Merge a modular configuration into a single file.
The bitrise yml get, bitrise yml update, and bitrise stack list commands, and online validation, need Bitrise CLI 3.0.0 or newer, and an access token: see Authenticating with the Bitrise CLI.
The CLI has more tools for a bitrise.yml file on your own computer:
- To generate a
bitrise.ymlfor your project, runbitrise local init: Initializing a Bitrise project locally. - To edit a
bitrise.ymlin a graphical editor, run the offline Workflow Editor: Installing and upgrading the offline Workflow Editor. - To run a Workflow from a
bitrise.yml, runbitrise local run: Running your first local build with the CLI.
Downloading the bitrise.yml fileClick to copy link
bitrise yml get prints the bitrise.yml that Bitrise stores for a project. Save it to a file to edit or run it locally:
bitrise yml get --app my-app-id > bitrise.yml
To get the bitrise.yml that a specific build ran with, add --build with the build's ID. bitrise build yml does the same:
bitrise yml get --app my-app-id --build abc123
bitrise build yml abc123 --app my-app-id
With --format json or --format yml, the CLI prints an object with the project's ID, the build's ID, if you set one, and the configuration as a single string in the content field. To save the file itself, use the default raw format.
Uploading a bitrise.yml fileClick to copy link
bitrise yml update replaces the bitrise.yml that Bitrise stores for a project. Pass the file with --file, or send it to the standard input:
bitrise yml update --app my-app-id --file bitrise.yml
bitrise yml update --app my-app-id < bitrise.yml
If the project stores its bitrise.yml in the repository, the command succeeds but builds keep using the file in the repository. Commit your changes to the repository instead.
Bitrise stores the configuration as structured data, not as the file you upload. Comments, key order, and YAML anchors are lost: a later bitrise yml get returns an equivalent, reformatted file.
Inside a Bitrise build, the command updates the project the build runs for if you don't pass --app. Always pass --app when you update a different project from a build.
To catch mistakes before you upload, validate the file first.
Validating a bitrise.yml fileClick to copy link
bitrise yml validate checks the bitrise.yml in the current directory, or any configuration YAML file you point it to. If the current directory has a .bitrise.secrets.yml file, the command validates it together with the bitrise.yml:
bitrise yml validate
If you're logged in to Bitrise, the CLI validates the file with the Bitrise API. With --app, the API also checks settings that depend on the project, such as stacks, machine types, and license pools:
bitrise yml validate --app my-app-id
If you're not logged in, you add --offline, or the online check can't complete, the CLI only checks the file against the bitrise.yml schema on your computer.
To validate a different configuration YAML file, use these flags:
| Flag | What it takes |
|---|---|
--config | The path of the file, or - to read it from the standard input. |
--config-base64 | The file's content, encoded in Base64. |
--inventory | The path of a Secrets file to validate with the configuration. Without this flag, the CLI validates .bitrise.secrets.yml in the current directory, if it exists. |
--inventory-base64 | The Secrets file's content, encoded in Base64. |
bitrise yml validate --config ./ci/bitrise.yml
To print the result as JSON or YAML, add --format json or --format yml. The command doesn't use the default output format from your configuration.
Merging a modular configurationClick to copy link
A modular configuration splits a bitrise.yml into several configuration YAML files with include statements. bitrise yml merge resolves the includes and prints a single bitrise.yml, followed by the tree of the included files.
By default, the command merges the bitrise.yml in the current directory. To merge a configuration YAML file with a different name or location, pass its path. The merged output is always named bitrise.yml:
bitrise yml merge
bitrise yml merge ./ci/bitrise.yml
To write the result to files instead, pass a directory with --output. The CLI writes the merged configuration to bitrise.yml and the file tree to config_tree.json in that directory:
bitrise yml merge --output ./merged
Finding stack IDsClick to copy link
To set the stack of a build in bitrise.yml, you need the stack's ID. bitrise stack list lists the available stacks with their IDs, operating systems, and statuses:
bitrise stack list
If the CLI finds a Workspace, from --workspace, BITRISE_WORKSPACE_ID, or default_workspace_id, it lists the stacks available to that Workspace, including its custom stacks. Otherwise, it lists the stacks available to everyone.
bitrise stack list --workspace my-workspace-id
Use the ID in the meta section of your bitrise.yml:
meta:
bitrise.io:
stack: osx-xcode-latest-stable