Create a package

Execute the command below to create a new package named hello.

$ bal new --template lib hello

This creates the files below.

$ cd hello
$ tree .
    .
    ├── Ballerina.toml
    ├── README.md
    ├── hello.bal
    ├── resources
    └── tests
        └── lib_test.bal

2 directories, 5 files

• The Ballerina.toml file identifies the directory as a Ballerina package. You can edit the Ballerina.toml file to change the organization, name, and version of the package. Additionally, you can add an icon, a description, and keywords to the package, allowing users to easily find it through search functions. To learn more about these fields, see The Ballerina.toml file
• The README.md is required when you publish a package to a repository. You can edit the content to add a meaningful description about the package.
• The hello.bal file, resources/ directory, and the tests/ directory belong to the default module of the package.

Info: For more information on these files, see Package layout.

To generate the Ballerina archive, execute the command below.

$ bal pack

You view the output below.

Compiling source
	user/hello:0.1.0

Creating bala
	target/bala/user-hello-any-0.1.0.bala

Publish a package to Ballerina Central

You can publish a Ballerina archive to the Ballerina Central. Before you publish, ensure the package works as intended because a publish is permanent. Once published to Ballerina Central, you cannot overwrite the version or remove the package. However, the number of package versions you can push to Ballerina Central is not restricted.

Tip: As a precaution, use the local repository first to test out the functionality of the package before publishing it to Ballerina Central.

Obtain an access token

1. Create an account on Ballerina Central. To register, visit the home page and log in via a Google, GitHub, Microsoft, or email account.

2. Navigate to the Dashboard and acquire an access token.

3. Download and place the Settings.toml file in your home repository (<USER_HOME>/.ballerina/). If you already have a Settings.toml file configured in your home repository, follow the other option and copy the access token into the Settings.toml as follows.

   [central]
   accesstoken="<token>"

   If you are working in a context where it is not possible to save the Settings.toml file (e.g., within a CI/CD pipeline) you can set the access token via the BALLERINA_CENTRAL_ACCESS_TOKEN environment variable.

   export BALLERINA_CENTRAL_ACCESS_TOKEN="<token>"
   

Note: The tokens remain valid for one year from the generation date. Upon expiration, you must generate a new token and update the Settings.toml file to avoid the unauthorized access error.

Configure proxy settings (optional)

If you are connected to the internet via an HTTP proxy, configure the proxy settings in the Settings.toml file to access the Ballerina Central to publish packages. For more information on proxy settings, see Configure a network proxy.

Define the organization

When you push a package to Ballerina Central, the organizations are validated against the value of the org field defined in the Ballerina.toml file. Therefore, when you have more than one organization in Ballerina Central, pick the organization name that you intend to push the package into, set that as the org in the Ballerina.toml file inside the package directory, and rebuild the package. If you do not have any organizations created, you can visit the organizations page to create one.

Also, organization names starting with ballerina (e.g., ballerina, ballerinax, ballerinai, etc.) are reserved for system use, and you cannot publish any packages starting with the ballerina prefix to Ballerina Central. Therefore, if you have used a name pattern matching this, update the Ballerina.toml and rebuild the package.

You can also choose who will have access to the package you are publishing by setting the package visibility in the Ballerina.toml file. If you set the visibility as private, it will only be visible and accessible to the members within the organization you are pushing the package into. Private packages will be visible on Ballerina Central only if you are logged in. Likewise, if you or a member of your organization wants to pull a private package, the Settings.toml file needs to be set up according to the previous section (if not set up already).

Publish the package

Now, that you are ready to publish, execute the command below to publish the package to Ballerina Central.

$ bal push

Publish a new version of a package

If you require adding new features/improvements/fixes to a package, which you have already published to Ballerina central, you are allowed to publish them under a new version, based on the Semantic Versioning Specification.

However, it's the package developer's responsibility to be cautious when deciding on the new package versions (especially when there are potential breaking/backward-incompatible API changes), as otherwise, it may result in package versions that are compatible only by the version but not by the implementation.

Tip: As a precaution, use the Ballerina semver validator CLI tool (experimental) to check if your new API changes conform to the version that you are trying to publish to Ballerina central.

By default, running the bal semver command on the root directory of the package will compare the local changes with the "closest compatible" published version available in Ballerina Central. (Use bal semver --help for the CLI help text which outlines all the available command options)

Note: Semver validator CLI support is only available from Swan Lake Update 2 onwards.

Use the packages in Ballerina Central

After publishing your first package, you can create a second package and use the already published package in it.

Info: For more information, see Import a module.

Deprecate packages published in Ballerina Central

You can deprecate a specific version or all versions of a published package due to name changes, bugs, or security vulnerabilities.

Deprecate all versions of a published package

For example, if you want to change the name of a published package, execute the command below to mark all the versions of the existing package as deprecated and then, publish the package under a new name.

Info: An optional deprecation message can also be included, which will be displayed to current users of the package.

$ bal deprecate <org-name>/<package-name> --message <deprecation-message>

Deprecate a specific version of a published package

For example, if you have released a package version containing a critical bug or security vulnerability, it is possible to deprecate that specific version.

To deprecate a particular version of a package on Ballerina Central, the package owner can run the same command with the package version.

$ bal deprecate <org-name>/<package-name>:<version> --message <deprecation-message>

Info: If the deprecated package or version is in use, a warning message containing the provided deprecation message will be shown during the project build. A deprecated package or version will not appear in package searches on Ballerina Central or the CLI. Additionally, it will not be used for dependency resolution unless it is already a part of a sticky build or no other compatible package version exists.

Undo deprecation of a package

Execute the command with the --undo flag below to reverse the deprecation of a package.

$ bal deprecate <org-name>/<package-name>[:<version>] --undo