title |
---|
\`auto\` Configuration File |
import { DefaultLabelRenderer } from "../../../components/defaultLabelsRenderer";
auto
uses cosmiconfig to find your config.
This means you can define this file a variety of ways.
cosmiconfig
will start at the root of your project and start to search up the directory tree for the following:
- a package.json property
- a JSON or YAML, extension-less "rc file"
- an "rc file" with the extensions
.json
,.yaml
,.yml
, or.js
- a
.config.js
CommonJS module
To interactively create an .autorc
use the init
command. You can configure most flags and all labels/changelogTitles.
auto init
The following are all of the top level configuration options for auto
.
While some of the following options also exist as flags to certain comments,
it is recommended to set them in an .autorc
so your commands are terser and experience consistent.
Configure the default release behavior.
{
"onlyPublishWithReleaseLabel": true
}
Configure what your repo considers the base branch.
Defaults to either main
or master
.
{
"baseBranch": "trunk"
}
It is useful to specify your plugins in the rc file rather than in all the commands.
{
"plugins": ["npm", "../path/to/plugin.js", "NPM_PACKAGE_NAME"]
}
If you are using enterprise github, auto
lets you configure the github API URL that it uses.
{
"githubApi": "https://github.mine.com/api/v3"
}
This is used for doing some searches in auto
.
The default behavior will construct the root API url for GitHub Enterprise.
If you are using enterprise github and your company hosts the graphql at some other URL than the githubApi
, you can use githubGraphqlApi
to set the base path for auto
.
{
"githubGraphqlApi": "https://github.mine.com/other/api/"
}
The name and email to use with git.
{
"author": "Joe Schmo <joe@schmo.com>"
}
or
{
"author": {
"name": "Joe Schmo",
"email": "joe@schmo.com"
}
}
Name to use with git.
NOTE: Will be deprecated in v10
{
"name": "Joe Schmo"
}
Email to use with git.
NOTE: Will be deprecated in v10
{
"email": "joe@schmo.com"
}
Do not make tags or releases with a v
prefix.
{
"noVersionPrefix": true
}
For some commands you can supply defaults for some options.
Example: Adding the following to you .autorc
will make auto
only release pre-releases to GitHub.
{
"release": {
"prerelease": true
}
}
Please refer to each command's documentation to see which options are configurable.
The following options can be set exclusively in the .autorc
and do not exist as CLI flags.
Create and manage old major releases.
{
"versionBranches": true,
// or customize the branch prefix
"versionBranches": "major-"
}
You can configure what branches auto
treats as prerelease branches.
By default only next
is treated as a prerelease branch.
If you configure prereleaseBranches
it will override the default.
{
"prereleaseBranches": ["next", "beta"]
}
To customize your project's labels use the labels
section in your .autorc
.
{
"labels": [
{ "releaseType": "major", "name": "Version: Major" },
{ "releaseType": "minor", "name": "Version: Minor" },
{ "releaseType": "patch", "name": "Version: Patch" },
{ "releaseType": "skip", "name": "NO!" },
{ "releaseType": "release", "name": "Autobots, rollout!" }
]
}
You can customize everything about a label
name
- The label text used for the label. If omitted defaults to thekey
valuereleaseType
- The type of release to trigger (major, minor, patch, skip, release, or none)overwrite
- Overwrite the default label(s) associated with thereleaseType
. (default:false
)changelogTitle
- The title to use in the changelogdescription
- The description to use when creating the labeldefault
- Marks this label as the default label for unlabelled PRs (patch
is the default "default label")color
- The color of the label. Can be specified as a string in any of these ways. If not specified the color is random
{
"labels": [
{
"name": "Version: Major",
"changelogTitle": "The API has changed:",
"description": "Add this label to a PR to create a major release",
"color": "blue",
"releaseType": "major"
}
]
}
A label with the none
release type will not create a release when merged.
If paired with a SEMVER label, the release is not skipped.
{
"labels": [
{
"name": "documentation",
"releaseType": "none"
}
]
}
Each PR included in the release will be assigned to a label section based upon the matching label with the highest releaseType
that has a changelogTitle
.
- Priority order of
releaseType
from highest to lowest is: major, minor, patch, and then all others - If a PR has multiple labels of the same
releaseType
, then the PR is assigned based upon the label that is assigned first in the config
By default auto will create sections in the changelog for the following labels:
major
minor
patch
internal
documentation
For example:
- Using the default config, if a given PR has the labels
minor
andinternal
, then it will be included in theminor
label section - Using the default config, if a given PR has the labels
documentation
andinternal
, then it will be included in theinternal
label section
To customize the title for the section in the changelog you can
{
"labels": [
{
"name": "documentation",
"changelogTitle": "Docz"
}
]
}
If you want more sections in your changelog to further detail the change-set you can
use the labels
section to add more. Any label in the label section with a changelogTitle
will become a special section in your changelog.
The following adds a typescript
label to the project that we can use to denote changes
related to a TypeScript re-write.
{
"labels": [
{
"name": "typescript",
"changelogTitle": "TypeScript Rewrite"
}
]
}
You can remove the existing default label sections by adding a custom overwrite label with the same releaseType
.
The following removes the default internal and documentation label sections:
{
"labels": [
{
"name": "Custom Doc Label",
"changelogTitle": "Docz",
"releaseType": "none",
"overwrite": true
}
]
}
If you want to share your auto configuration between projects you can use the extends
property.
This property will load from a module's package.json
or from a custom path.
It's expected that the extended configuration be under the auto
key in the package.json
file.
Auto can load extends
configs in the following ways:
- from a path
./path/to/config
(this file must be in JSON format) - from a scoped package
@YOUR_SCOPE/auto-config
(under theauto
key in the package.json) - from a package
auto-config-YOUR_NAME
- from a url
https://yourdomain.com/auto-config.json
(must return the content typeapplication/json
)
{
"extends": "@YOUR_SCOPE"
}
Will use the package @YOUR_SCOPE/auto-config
{
"extends": "joe"
}
Will use the package auto-config-joe
⚠️ If extending from a config package make sure it's a dependency of your project
If you're extending from a local file it can be any file in JSON format or a package.json
file.
{
"extends": "./path/to/config.json"
}
{
"extends": "./path/to/other/package.json"
}
An extends
configuration can include custom plugins in the NPM package.
This is useful if you have a shared plugin that doesn't necessarily need to be published as it's own package.
NOTE: This does not work for
auto
configs stored in a url.
To include custom plugins just use a relative path in the extended configuration/
package.json
:
{
"auto": {
"plugins": ["./plugins/some-plugin.js"]
}
}