README.md
author Aki Sasaki <asasaki@mozilla.com>
Thu, 21 Jan 2021 02:11:04 +0000
changeset 272 69a32178341a51a994e2b07f34c359f13492f964
parent 199 f7e192c9864aec77c9d38e833e7129cc7ecc9795
permissions -rw-r--r--
Bug 1676867 - create hooks for repos with non-standard default_branch. r=taskgraph-reviewers,jmaher Differential Revision: https://phabricator.services.mozilla.com/D102510

**Manage runtime configuration for Firefox CI**

# Overview

This tool is for the management of taskcluster resources, such as roles and hooks. It can download existing resources and compare them to a stored configuration.
A collection of resources also specifies the set of managed resources: this allows controlled deletion of resources that are no longer expected.


# Initial Setup
1. Create and activate a new python virtualenv
1. pip install -e .
1. If you will be applying changes, ensure you have a way of generating taskcluster credentials, such as [taskcluster-cli](https://github.com/taskcluster/taskcluster/releases)

# Starting Concepts

This tool examines the contents of the `ci-configuration` repository, as well as examining and applying changes to the running taskcluster configuration.

The `environment` describes the cluster being affected, such as `firefoxci` or `staging`. There is also a [community](https://github.com/mozilla/community-tc-config/) environment which is managed separately.

You will usually want to check the changes that will be applied using `ci-admin diff` and then apply them using `ci-admin apply`

You can supply `--grep` to both 'diff' and 'apply' options to limit the effects to specific changes.

# Making Config Changes

1. Make changes in a local clone of https://hg.mozilla.org/ci/ci-configuration
1. Record the directory used for the clone in Step 1. If you're in that directory, then:

   `export CI_CONFIG_PATH="$(realpath "$(pwd)")"`

   (As the `check` subcommand can't cope with relative paths like `.`)
1. Determine which taskcluster environment is relevant, such as `firefoxci`
1. Use the `ci-admin diff` and `ci-admin check` to ensure the changes are what you expect.

   Remember `--ci-configuration-directory` and `--environment`

   Examples:

   * `ci-admin diff --environment=firefoxci --ci-configuration-directory="$CI_CONFIG_PATH"`
   * `ci-admin check --environment=firefoxci --ci-configuration-directory="$CI_CONFIG_PATH"`

1. Submit changes to Phabricator for review, and land once approved.
1. Use `ci-admin diff --environment=firefoxci` to display the changes that would be applied. We want to use the remote repository for this step so do not use `--ci-configuration-directory`
1. Generate some taskcluster credentials, such as `taskcluster signin`.
1. Apply the generated configuration using **either**
   * `ci-admin apply --environment=firefoxci` to apply all of the generated configuration
   **or**
   * `ci-admin apply --environment=firefoxci --grep my-changes` to apply only the selected areas of new configuration.

   Which you choose will depend on the current state of the `ci-configuration` repository and whether there are multiple changes waiting to be applied at a later time.

You will be shown a summary of the changes that have been applied.

# More Information

* **`ci-admin diff --environment=firefoxci`**

   Generate a diff of the currently running taskcluster configuration,
   and the one generated from the tip of the ci-configuration repository.

* **`ci-admin diff --environment=firefoxci --grep somestring`**

   The `grep` option will return full configuration entries relating to the
   provided string. For example, if you have added a new action called `my-action`
   then `--grep my-action` will show only those entries.

* **`ci-admin diff --environment=firefoxci --ci-configuration-directory /path/to/ci-configuration/`**

  This option is useful if you are still working on changes and they are not yet in the remote `ci-configuration` repository.

  It will instead use the specific path as configuration as the 'new' side when comparing against the currently running state.

  *Warning* Due to some limitations it is best to supply an absolute path to the `ci-configuration` repository, or calculate it in the shell, such as `--ci-configuration-directory "$(realpath ../ci-configuration/)"`


* **`ci-admin generate`**

  Generates the expected CI configuration. Use `--json` to get JSON output.

* **`ci-admin current`**

  Produces the currently running CI configuration. This also understands `--json`.

  `generate` and `current` are two steps run automatically when using `ci-admin diff`

* **`--ci-configuration-directory`** and **`--ci-configuration-revision`**

  As mentioned above you can point these tools to a local copy of the repository with `--ci-configuration-directory`. It is recommended to use an absolute path, which can be easily set using `$(realpath ../relative/path)`

  You can also point to a different revision with `--ci-configuration-revision`. If you don't specify a revision, the current tip of the repository will be used. Without specifying a directory, the remote repository is used. It's valid to specify one, both, or neither option to get different behaviours.

* **`ci-admin <sub-command> --help`**

  Each command should have helpful text here. Please add some if it's missing.